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PREFACE 



The TOPS-20 System Manager' s Guide is written for the person who is 
responsible for establishing policies and procedures for a timesharing 
and/or batch processing installation, using the TOPS-20 Operating 
System. Usually, this person is responsible for setting up and 
maintaining both the system hardware and software. The Site 
Management Guide and the TOPS-20 Operator's Guide provide you and your 
operations people with the necessary information to maintain your 
system hardware. These two manuals are referenced throughout this 
guide. 

This guide deals primarily with your system software. It contains 
general suggestions for planning the installation of your software and 
for setting up your computer room to begin operations. The guide 
contains hints and suggestions for your system's operation, including 
when, and many times why, particular functions or procedures should be 
considered. It assumes that your system operator is responsible for 
implementing many of the decisions you make. In most cases, where 
lengthy implementation procedures are required, the appropriate 
reference is noted. 

Chapters 1 and 2 describe the documentation, system logs, and 

special forms that you should have available to 
you, and in some cases, to system users. 
Chapter 2 also includes preliminary planning 
functions that you can do before the software 
is installed. 

Chapter 3 describes the system directories and files that 

your system contains immediately after you 
install the software. It also describes the 
mechanisms you can use to change the installed 
TOPS-20 batch system and to test the integrity 
of your newly installed or updated system. 

Chapter 4 describes using your disk-pack and disk-drive 

resources to set up disk structures in a way 
that best suits your installation's needs. It 
also includes guidelines for determining the 
available disk space that you have to create 
user directories. 
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CHAPTER 1 
DOCUMENTATION 



Section 1.1 describes the documentation provided by DIGITAL and 
recommends the manuals with which you should be familiar to manage 
your system. Section 1.2 describes adding your own documentation, for 
example, special forms, to the documentation you receive from DIGITAL. 
Be sure you have all available documentation convenient to your system 
users. 



1.1 DOCUMENTS AVAILABLE FROM DIGITAL 

All documentation for the TOPS-20 Operating System is contained in the 
TOPS-20 Software Notebook Set. This notebook set contains information 
pertaining to the most recent version of TOPS-20. It is organized 
functionally to facilitate referencing manuals. Each manual contains 
cross references to other manuals within the set that further explain 
a subject. 

This manual assumes that you are familiar with some of the manuals in 
the notebook set. In particular, you should be familiar with the 
information in the TOPS-20 Operator's Guide , the TOPS-20 User's Guide , 
the DECSYSTEM-20 Technical Summary , and the TOPS-20 KL10 Model B 
Installatio n Guide . 

Any additional documents that you need depend on the configuration of 
your system. For example, if your system has IBM emulation and 
termination (DNxx) , you should be familiar with the IBM 
Emulation-Termination, DN64 DN65 Manual . It includes installation 
procedures and descriptions of the operator and user interfaces. If 
your system is connected to the ARPA network, you should have access 
to the TOPS-20AN Monitor Calls User's Guide and the TOPS-20AN User's 
Guide . If your system has DECnet, you should be familiar with the 
various DECnet-20 manuals. If you are using LAT terminal servers in 
an Ethernet local area network, refer to the documentation that is 
provided with LAT terminal servers, in addition to chapter 13 of this 
manual . 

In addition to the TOPS-20 Software Notebook Set , you receive the 
TOPS-20 Beware File Listing. It is distributed with the software 
installation and distribution magnetic tapes. Before installing a new 
version of the software on your system, read the Beware File. It 
contains last-minute changes to the software that have not been 
documented, and hints or suggestions for installing or using the new 
software. 
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With each new system, you should also receive two stand-alone 
documents, which are documents not included in the notebook set. 
These manuals assist you in 1) preparing your site for the hardware 
installation, the Site Preparation Guide, and 2) maintaining and 
reporting problems about your system's software and hardware, the Site 
Management Guide. 

NOTE 

Your Sales Representative delivers the Site 
Preparation Guide, and your Field Service 
Representative delivers the Site Management Guide. 

This manual (the TOPS-20 System Manager's Guide ) deals primarily with 
installing and maintaining the software on your system. Therefore, it 
is assumed that you have already used the Site Preparation Guide to 
install your system hardware. 

The Site Management Guide is designed for use by both you (along with 
your operations people) and your Field Service Representative. You 
should begin using this manual immediately after you install your 
hardware. It contains schedules, procedures, and logs for recording 
and evaluating all information pertinent to the operation and care of 
the system. The manual belongs to DIGITAL, but it is kept and 
maintained at your computer site. For added convenience and 
organization, many system managers keep all their important system 
information in the same binder as the Site Management Guide. For 
example, they keep System Logs and Operator Shift Change information 
in the same binder, along with other special forms. Section 1.2 
describes several forms that you may include in a system log book or, 
as suggested here, in the Site Management Guide. 

DIGITAL places a major emphasis on the documentation provided to its 

customers. The Software Publications Department continues to solicit 

suggestions for improvement and corrections from the users of its 

documentation. Encourage users to comment on the ma;nuals you receive 

with your system. For convenience, a Reader Comment Form is located 
at the back of each manual. 



1.2 DOCUMENTS PREPARED AT YOUR INSTALLATION 

Sections 1.2.1 through 1.2.5 describe some forms that may be useful at 
your installation. A sample form is provided in each section. 
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1.2.1 System Log 

Every system must have a system log for recording problems and 
procedures relating to both hardware and software. All operators and 
system programmers should record the following types of activities in 
the log, along with the date, time, and their names: 

• System backup procedures 

• Beginning and ending of timesharing (for example, the times 
the system was started and stopped for preventive maintenance 
or repair) 

• Problems in hardware or software AND the actions taken to 
correct the problems (always save the CTY (operator terminal) 
output or copy of the typescript) 

• New or revised software installed 

• New users or changes to existing user data or directories 

• New structures or changes to existing structures 

Most system problems are easier to solve (and, hence, less costly) if 
you keep an accurate record of all activities. The Site Management 
Guide has a section set aside for system log information. This 
section contains preprinted forms that you can use to record system 
log information, or you can design your own forms. You can store 
these forms in the Site Management Guide or in a separate binder. 

You should design your log so that it is easy to use and read; 
Remember, you are likely to have the most problems when the system is 
new, so NOW is the time to start using the log. The following two 
pages contain sample left- and right-hand pages of a log book. The 
left-hand page (Figure 1-1) contains information concerning hardware 
maintenance; the right-hand page (Figure 1-2) is a problem report, 
containing: 

• The time of the entry 

• A "Y" or "N" answer to whether the system had to be reloaded 

• The name of the person making the entry 

• A few words describing the nature of the activity 

• A record of calls to Digital Field Service (F/S) 

• A description of the device or program causing the problem 

• Remarks about the entry 



1-3 



DOCUMENTATION 



SYSTEM LOG 

MAINTENANCE PERFORMED DATE. 



MR-S-526-80 



Figure 1-1: Sample System Log (Hardware Maintenance) 
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Figure 1-2: Sample System Log (Problem Report) 
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1.2.2 Mountable Structure Sign-Up Log 

In addition to keeping the system log, you should also record requests 
from users to mount structures. (Chapter 4 describes how to set up 
and use structures.) Without a formal scheduling procedure, some users 
may monopolize the use of a structure and frustrate other users, who 
do not have the opportunity to mount and use their structures, usually 
because there are no disk drives available. To avoid this situation, 
set up a procedure whereby users inform the operator when they need to 
use a structure. The operator can then schedule the length of time 
specified on the request log. On a busy day, when many users are 
issuing mount requests for structures, the operator checks the log 
before granting or denying the mount requests. This scheduling allows 
you to service many requests for mounting structures in a fair and 
orderly manner. The sample Mountable Structure Sign-Up Log shown in 
Figure 1-3 contains: 

• The scheduled mounting time 

• The scheduled time needed to use the structure 

• The actual time the structure was mounted 

• The actual time the structure was removed 

• The name of the user who initiated the request 

• The structure name (or pack ID) 

• A column for any special instructions or notes 

Remember that this log is only a sample; you should design a form that 
best suits your own requirements. 



1.2.3 System Access Request Form 

Some installations have many users requesting access to the system for 
the first time. You need standard information from these users before 
you can process their requests and create directories for them. For 
example, you must know which system they need to access (if you have 
more than one system), their names, selected passwords, departments, 
accounts, etc. You can organize these requests by providing a System 
Access Request Form that is kept in an easy-to-access area, perhaps 
outside the computer room. You can require signatures of department 
managers on the access form to ensure that prospective users have 
approval to charge computer usage to accounts. Figure 1-4 is a sample 
of a system access request form. 

If you are using CFS-20 software, refer to Chapter 12, The Common File 
System, for further considerations in assigning users to systems. 
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Figure 1-3j Sample Mountable Structure Sign-Up Log 
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1.2.4 Operator Work Request Form 

You may want a form that allows users to request work from the 
operator. Examples of requests made to the operator are initializing 
tapes, transferring files between systems, and making changes to 
directories. You should set up a procedure for handling these 
requests. Figure 1-5 is a sample of an operator work request form. 



1.2.5 Operator Shift Change Log 

You may want to set up a binder to contain operator shift change 
information. Each operator records new procedures, or special 
instructions that the incoming operator needs to know. The incoming 
operator reads the operator shift log before starting the new shift. 
For example, the first shift operator changes the procedure for 
storing tapes, and records the new procedure in the shift change log. 
The information in the shift change log should not concern problems 
with the system, but should contain important information about the 
system or the computer room. The incoming operator still reads the 
system log book to determine the status of the system and any problems 
that have occurred during the previous shift. Figure 1-6 is a sample 
of an operator shift change log. 
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Figure 1-6: Operator Shift Change Log 
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and 
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that 
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can 
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Chapter 6 



Chapter 7 



Chapter 8 



Chapter 9 



Chapter 10 



Chapter 11 



describes the TOPS-20 accounting facility. This 
description includes how to choose an 
accounting scheme, how to crepte accounting 
files, and how to set the system to begin 
validating accounts. 

describes backing up your disk structures onto 
magnetic tape soon after software installation. 
It recommends the supplies: needed and 
procedures that you should follow to save all 
your directories and files on a daily basis, 
and how to create a system crash tape in the 
event of a major problem with the file system. 

describes how you can use magnetic tapes to 
store important files (file archiving) and to 
save valuable disk space by copying 
infrequently accessed files to tape (file 
migration) . It also describes how to give 
control of tape drive usage to| the system and 
the operator (tape drive allocation) , and how 
to set up your system to use labeled tapes 
(tape labeling) . 

describes the procedures you must follow in the 
event that you have a problem with the file 
system or that a user has lost the files in a 
directory. It describes using your system crash 
tape and your daily backup tapbs to resolve 
these problems. 

describes the tuning mechanisms that allow you 
to change the behavior of your system. Each 
description includes why you may want to use a 
particular mechanism, how to use it, and the 
effects it may have on your system. 

describes the access control mechanisms that 
you can use to alter system policy decisions or 
to increase security against unauthorized 
system use. This chapter includes the type of 
policy changes you may want to make at your 
installation. 



Chapter 12 



Chapter 13 



describes the Common File System, a software 
feature of TOPS-20. This chapter discusses the 
rules, options, and restrictions associated 
with sharing files among systems:. 

describes the Local Area Transport (LAT) 
software, for use with terminal servers in 
Ethernet local area networks. 



The following conventions and symbols are used throughout this guide: 
Convention/Symbol Description 



n- 
UPPERCASE 

lowercase 
red print 


<RET> 

CTRL/ 



n refers to the latest version of a particular 
file, for example, 6-1-CONFIG.CMD. 

In user input representations, indicates 
information that must be entered exactly as 
shown. 

In user input representations, indicates 
variable information that is determined by you. 

Indicates the information that you must type at 
your terminal. 

In user input representations, encloses guide 
word information. Pressing the ESCAPE or 
ALTMODE key on your terminal causes guidewords 
to be printed by the computer. 

Indicates you should press the RET or RETURN 
key on your terminal. Unless otherwise noted, 
pressing RETURN terminates all command or input 
strings. 

Indicates you should press the CTRL key on your 
terminal. The CTRL key is always used in 
conjunction with another key, for example, 
CTRL/Z. 
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CHAPTER 2 
PREPARING FOR SOFTWARE INSTALLATION 



You can establish many of the policies and procedures for your 
computer site before you install the software. It may help you later 
if some of the preliminary decisions and preparations are done before 
you begin setting up the system and handling requests from users. The 
following suggestions for preparing your installation are not 
all-inclusive. Some TOPS-20 installations have specific requirements 
or restrictions that are not considered here. You can use this list 
as a guideline for the types of decisions you can make in the early 



stages of setting up your computer site. 



2.1 SECURING THE COMPUTER ROOM 

Select the type of computer room security you need and a method of 
enforcement. Many system managers do not allow non-operations people 
to enter the computer room. Establish an open- or closed-door policy, 
and notify users of your policy. If you decide on a closed-door 
policy, notify users of the procedures that they should use to contact 
you (or the operator) and to submit their job requests. 



2.2 HANDLING USER REQUESTS 

Determine how user requests will be handled. You can handle jobs on a 
first-come basis, or on a priority basis. You can set up request 
boxes outside the computer room that the operator checks regularly. 
You can also establish a location where users can leave disks and 
tapes for the operator to mount. Post a sign-up sheet so that users 
can specify the time they need the tape or disk mounted. Chapter 1 
describes sample forms that can be completed by users to request 
initial access to the system and to request that work be done by the 
operator. 



2.3 ORDERING SUPPLIES 

Assign someone the responsibility for ordering paper supplies, 
ribbons, cards, and magnetic tapes. Chapter 7 provides an estimate of 
the number of tapes you should have to begin a backup procedure 
immediately after you install the software. Be sure you have enough 
CTY (operator terminal) and line printer paper to begin operations. 
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2.4 SCHEDULING OPERATOR TASKS 

The operator performs tasks either on a regular basis or on an 
as-needed basis. Decide which operator tasks will be performed on a 
regular schedule. Be sure to include hardware, software, and 
documentation related tasks. These regularly scheduled tasks can be 
performed daily, weekly, or monthly. 



The following lists are samples of hardware- 
tasks that your operator may perform. 



and software-related 



Hardware-Related Tasks 


Regular Schedule 


As-Needed Schedule 


Clean tops of disk drives. 


Replenish paper in the line 




printer. 


Clean magnetic tape drives. 


Remove reports from the line 




printer and distribute (perhaps 




to mail boxes) . 


Vacuum line printer to remove 


Replenish paper in operator's 


paper chad. 


console. 


Load mountable structures 


Physically load and unload 


according to a schedule. 


magnetic tape and disk drives. 



Software-Related Tasks 



Regular Schedule 


As-Needed Schedule 


Bring up system after weekly 
maintenance. 

Run scheduled batch production 
jobs. 

Save the contents of disk on 
magnetic tape. 

Create a system "crash" tape 
for backup. 

Run the SPEAR program for daily 
error analysis. 

Submit a daily control file for 
accounting. 

Create the Message-of-the-Day 
with the MAIL program. 


Bring up system after a crash. 

Maintain the batch system for 
users. 

Save special disk areas on 
magnetic tape. 

Restore selected user disk 
areas as needed. 

Interact with users. 

Create and update user 
directories. 

Monitor disk space. 



Establish a location for keeping the hard-copy output from the CTY. 

Your Field Service Representative needs this information if you have 

problems with your system. Have the operator tear off the copy and 
store it daily. 
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Documentation-related tasks include: 

• keeping a hand-written log of system activities (System Log) 

• recording operator shift change information (Operator Shift 
Change Log) 

• coordinating the mounting and dismounting of structures 
(Mountable Structure Sign-up Log) 

Chapter 1 describes creating a system log, an operator shift change 
log, and a mountable structure sign-up log. 



2.5 SELECTING SYSTEM FEATURES 

Determine the system features you want to enable during software 
installation. When you install the software, you create a file called 
n-CONFIG.CMD. This file is read by a start-up program (n-SETSPD) when 
the system is started for the first time and each subsequent time that 
you reload and start the system. The n-CONFIG.CMD file defines the 
line speeds for your terminals and many system parameters. Most of 
the decisions you must make concerning the parameters in this file are 
described throughout this manual. As you read each chapter, you can 
list the parameters that you want to place in the n-CONFIG.CMD file. 
Many system managers choose to introduce new pieces of software 
slowly. Therefore, you may want to disable some of the parameters 
until you have run the new software for awhile. You can edit the 
n-CONFIG.CMD file to add new software features to the system. You 
should edit the file at a convenient time before you reload the 
system. Then, when the system restarts, the new software features are 
enabled. 

Chapters 3 through 13 describe setting up and maintaining your system. 
Read these chapters thoroughly. They contain important information to 
help you make decisions both before and after you install the 
software. 
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CHAPTER 3 
AFTER SOFTWARE INSTALLATION 



3.1 OVERVIEW 

After you install the TOPS-20 software, your system contains all the 
directories and files necessary for you to start preparing for 
timesharing and batch processing. This chapter describes the 
directories, files, and system logical names created during software 
installation. Also included are suggestions for creating additional 
directories and logical names to assist you and system users. 



3.2 SPECIAL SYSTEM DIRECTORIES 

You initialize the file system during software installation. At this 
time, the system automatically creates nine directories on the disk 
that you defined as the system structure. These directories are shown 
in Figure 3-1: 




< Root-Di rectory > 

< System > 
<Subsys> 

< New-System > 
<New-Subsys> 
<Accounts> 
<Operator> 

< Spool > 

< System-Error > 




Figure 3-1: Special System Directories 



Sections 3.2.1 through 3.2.7 describe these directories and their use. 
Section 3.2.8 describes additional directories you can create and how 
they are useful. 

Chapter 5 also describes creating directories and includes diagrams 
showing the structure of directories. 
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3.2.1 <ROOT-DIRECTORY> 

The <ROOT-DIRECTORY> contains a separate file for each first level 
directory on the system structure as follows: 

STR: <ROOT-DIRECTORY> 
STR:<SYSTEM> ... STR:<SUBSYS> ... STR: <DIRECTORY> 

(where STR: is the name of the structure) . 

The <ROOT-DIRECTORY> is the most important directory created. Without 
it, directories and files cannot be accessed. You must NEVER modify 
this directory. The system maintains a backup copy of 
<ROOT-DIRECTORY> that can be accessed if the original copy is 
destroyed. (Refer to Section 9.3, RESTORING <ROOT-DIRECTORY>.) 

Each structure you create in addition to the system structure has a 
<ROOT-DIRECTORY>. The <ROOT-DIRECTORY> on any structure points to all 
the first-level directories created under the <ROOT-DIRECTORY>. 

After you install the software, give the DIRECTORY command for 
<ROOT-DIRECTORY>. The output on your terminal appears similar to the 
example below. Note that each directory is a file in the 
<ROOT-DIRECTORY>. The differences between this list and the one on 
your terminal depend on the model system you have and the type of 
unbundled software you have purchased. 

$DIRECTORY (OF FILES) STR: <ROOT-DIRECTORYXRET> 

STR: <R0OT-DIRECT0RY> 
ACCOUNTS. DIRECTORY. 1 

BACKUP-COPY-0F-RO0T-DIRECTORY. IMAGE. 1 
BOOTSTRAP. BIN. 1 
DSKBTTBL..1 

FRONT-END-FILE-SYSTEM.BIN. 1 
INDEX-TABLE.BIN. 1 
NEW-SUBSYS . DIRECTORY. 1 
NEW-SYSTEM . D IRECTORY . 1 
OPERATOR. DIRECTORY. 1 
ROOT-DIRECTORY. DIRECTORY. 1 
SPOOL. DIRECTORY. 1 
SUBSYS . DIRECTORY . 1 
SYSTEM. DIRECTORY. 1 
SYSTEM-ERROR. DIRECTORY. 1 
UETP. DIRECTORY. 1 

Total of 14 Files 



3.2.2 <SYSTEM> 

The directory <SYSTEM> contains data and program files that the system 
uses during normal operation. Table 3-1 lists many of the files that 
appear in this directory. 
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Table 3-1 s <SYSTEM> Files 



File Name 


Explanation 


0DUMP11.BIN 


Contains a dump of front-end memory 
after the front end crashes. 


2060-MONBIG.EXE 


The smallest runnable monitor. 


2 060-MONMAX.EXE 


The largest runnable monitor. 


n-CONFIG.CMD 


Contains definitions of line speeds, 
system logical names, printer VFU 
files, magnetic tape logical unit 
numbers, DECnet parameters, and 
additional system-dependent 
parameters. These system parameters 
are set every time the system starts. 
The value n equals the latest release 
of TOPS-20. 


n-PTYCON.ATO 


Contains the commands that are given 
automatically at the operator's 
console every time the system starts. 
You may modify this file to suit your 
own installation. 


n-SETSPD.EXE 


Program that reads the n-CONFIG.CMD 
file and sets up the parameters that 
it contains. The value n equals the 
latest release of TOPS-20. 


n-SYSJOB.EXE 


Program that runs in a process created 
by the monitor and takes commands from 
the file n-SYSJOB.RUN. 


n-SYSJOB.RUN 


Contains commands that SYSJOB 
processes. 


ACCOUNTS-TABLE.BIN 


Contains the information necessary to 
validate accounts. 


AN-MONBIG.EXE 


A large ARPANET timesharing monitor. 


AN-MONDCN.EXE 


A monitor that includes ARPAnet and 
DECnet. 


AN-MONMAX.EXE 


The largest ARPANET timesharing 
monitor. 


BUGS. MAC 


Contains a list of all BUGHLT, BUGINF, 
and BUGCHK messages. 


CHECKD.EXE 


Program that creates structures and 
checks file-system consistency. 


DEVICE-STATUS .BIN 


Contains status information for tape 
drives, disk drives, and disk 
structures. It is maintained by 
MOUNTR. 
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Table 3-1: <SYSTEM> Files (Cont.) 



File Name 



DUMP.CPY 



DUMP. EXE 

ERRMES.BIN 
EXEC. EXE 
FEDDT.EXE 

HOSTS.TXT 

INTERNET . GATEWAYS 

IPALOD.EXE 

KNILDR.EXE 

MONITR.EXE 
MONNAM.TXT 

PROGRAM-NAME-CACHE . TXT 

REAPER.CMD 

RSX20F.MAP 

SYSJOB.HLP 
SYSTEM.CMD 



Explanation 



Contains a copy of main memory at the 
time of the last system crash. It is 
copied from DUMP. EXE to maintain a 
history of crashes. This file is 
written by the n-SETSPD program when 
the system is rebooted. 

Contains a copy of main memory at the 
time of the last system crash. You 
must have this file to get a system 
dump after a crash. 

Contains binary system error messages. 

The TOPS-20 Command Processor. 

A DDT program used for debugging the 
front end. 

Defines ARPAnet host names and their 
number translations. 

Defines the network gateways for 
reaching host systems on remote 
networks. 

Program that loads the CI20 microcode. 

(The microcode is contained in the 

file.) After the loading has 

completed, TOPS-20 starts the CI. 

Program that loads the NIA20 
microcode. (The microcode is contained 
in the file.) It is run automatically 
at system startup to start the NI. 

The current monitor. 

Contains the monitor name printed at 
the beginning of the system greeting 
line. 

Contains a list of the programs that 
should be loaded into the program-name 
cache. Read by the MAPPER program. 

Contains a list of default commands to 
REAPER. The REAPER program reads this 
file each time it is run. 

Contains symbol locations for the 
front-end processor. It is used by the 
FEDDT program. 

Contains information about the SYSJOB 
program. 

Contains OPR commands and is read by 
the OPR program at system startup. 
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Table 3-1: <SYSTEM> Files (Cont.) 



File Name 


Explanation 


TAPNAM.TXT 

TGHA.EXE 
TGHA.HLP 
TOPS-20.DOC 


Text file that contains the 
installation identifier that is 
written on V0L1 labels for labeled 
tapes. 

Program that analyzes and corrects MOS 
memory problems. 

Contains information about the TGHA 
program. 

Text file that contains summary 
information about the latest release 
of TOPS-20. 



3.2.3 Restoring the Directory <SYSTEM> 

If the contents of <SYSTEM> are accidentally lost or destroyed, you 
can restore the directory from the TOPS-20 Installation Tape or your 
latest system backup tape. (Refer to Chapter 7 for information about 
creating system backup tapes.) Use the procedure below to restore 
<SYSTEM> directory. If you have enabled tape drive allocation, use 
the MOUNT command instead of the ASSIGN command. (Refer to Section 
8.3 for information about using tape drive allocation.) 



1. Mount the appropriate tape (in this example, it is on 
MTA0 : ) . 



drive 



2. Give the following commands at your terminal. 

@ENABLE (CAPABILITIES) <RET> 
$ASSIGN (DEVICE) MTA0 : <RET> 
$SKIP (DEVICE) MTA0: 4 FILES <RET> 
$RUN (PROGRAM) MTA0: <RET> 

DUMPER> TAPE (DEVICE) MTA0 : <RET> 

DUMPER> RESTORE (TAPE FILES) DSK* :<*>*.* .* (TO) <SYSTEM> <RET> 

DUMPER TAPE #1 , , FRIDAY l-NOV-85 330 
LOADING FILES INTO <SYSTEM> 

END OF SAVES ET 
DUMPER>EXIT <RET> 
$ 



3.2.4 <SUBSYS> 

The directory <SUBSYS> contains system programs (and their help files) 
that the user may want to run. The directory protection code set for 
<SUBSYS> prevents users from changing the files in this directory. 
Many of the file protections require users to enable WHEEL or OPERATOR 
capabilities to use the files. (Refer to Chapter 5 for information 
about directory and file protections and special capabilities.) Table 
3-2 lists the programs and files commonly placed in <SUBSYS>. An 
asterisk precedes all unbundled software. 
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Table 3-2: STR:<SUBSYS> Files 



Programs 



ACTGEN.EXE 

ACTGEN.HLP 
ACTSYM.UNV 

ANA UN V. UN V 
*B362LB.REL 

* BASIC. EXE 
BATCON. EXE 
CDRIVE.EXE 
CHECKD.EXE 

CHECKD.HLP 
CHKPNT.EXE 

CHKPNT.HLP 
CMD.REL 

CMD. UNV 

*COBDDT.HLP 

*COBDDT.REL 

*COBOL.EXE 

♦COBOL. HLP 

CREF.EXE 

CREF.HLP 

DIL.LIB 

DIL.REL 
DILV7.FOR 



Explanation 



Program that takes information from accounting 
files and creates the account validation data 
base. 

Contains information about the ACTG,EN program. 

A file of universal symbols for USAGE accounting 
programs. 

A file of ARPANET universal symbols. 

BLISS functions needed to rebuild the Record 
Management Services facility (RMS-20) from 
AUTOPATCH. 

The BASIC compiler. 

Program that controls batch jobs. 

Program that controls card readers. 

Program that creates structures and checks 
file-system consistency (same as in <SYSTEM>) . 

Contains information about the CHECKD program. 

Program that makes accounting entries in the file 
<ACCOUNTS>CHECKPOINT.BIN. 

Contains information about the CHKPNT program. 

A library file of routines for the COMND monitor 
call. 

A file of universal symbols for the COMND monitor 
call. 

Contains information about COBDDT. 

The COBOL debugging program. 

The COBOL compiler. 

Contains information about the COBOL compiler. 

Program that produces a cross-reference listing. 

Contains information about the CREF program. 

A library file of data definitions for COBOL 
programs that use the Data Interchange Library 
(DIL) facility. 

The DIL subroutines. 

Contains data definitions for FORTRAN programs 
that use DIL. 
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Table 3-2: STRs<SUBSYS> Files (Cont.) 



Programs 



DITV7.F0R 

DIXV7.F0R 

DLUSER.EXE 

DLUSER.HLP 
DUMPER.EXE 

DUMPER. HLP 
DX20LD.EXE 
DXMCA.ADX 
EDDT.REL 

EDIT. EXE 
EDIT. HLP 
*FAL.EXE 
FE.EXE 

FE.HLP 

FEDDT.EXE 

FILCOM.EXE 

FILCOM.HLP 

FILDDT.EXE 

*FORDDT.HLP 
*FORDDT.REL 
FORMAT.EXE 

FORMAT. HLP 
* FOROTS.EXE 

* FORTRA.EXE 
GALGEN.EXE 



Explanation 



Contains data definitions for FORTRAN programs 
that use the data transmission component of DIL. 

Contains data definitions for FORTRAN programs 
that use the data conversion component of DIL. 

Program that saves and restores the directory 
parameters. 

Contains information about the DLUSER program. 

Program that saves and restores files to and from 
magnetic tape. 

Contains information about the DUMPER program. 

Program that loads DX20 microcode. 

Microcode for DX20 tape subsystem controller. 

A component of the debugging program for the 
TOPS-20 monitor. 

A line-oriented text editor. 

Contains information about the EDIT program. 

Program that 'listens' for DECnet file transfers. 

Program that is used when copying files from the 
front-end file system to the TOPS-20 file system 
and vice versa. 

Contains information about the FE program. 

The debugging program for the front end. 

Program that compares the contents of two files. 

Contains information about the FILCOM program. 

A DDT program used for examining the contents of 
system dumps (DUMP.CPY). 

Contains information about the FORDDT program. 

The FORTRAN debugging program. 

Program used to format RP04/RP06 disk packs while 
the system is in timesharing mode. 

Contains information about the FORMAT program. 

The FORTRAN object time system (operating system 
interface) . 

The FORTRAN compiler. 

Program that creates the parameter file for 
building the batch system. 
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Table 3-2: STR:<SUBSYS> Files (Cont.) 



Programs 



GLOBS. UNV 

GLXLIB.EXE 

HELP.HLP 

*IBMSPL.EXE 

INFO. EXE 

*ISAM.EXE 

*ISAM.HLP 
KDDT.REL 

KNILDR.EXE 
LCPORN.REL 
LCPTAB.REL 
*LIBARY.EXE 

*LIBARY.HLP 
*LIB012.EXE 

*LIBOL.REL 
LINK. EXE 
LINK.HLP 
LP64.RAM 

LP96.RAM 

LPTSPL.EXE 
MACREL.REL 
MACRO.EXE 
MACRO. HLP 
MACSYM.UNV 
MAIL. EXE 
MAIL. HLP 



Explanation 



A file of universal symbols for the TOPS-20 
monitor. 

Object- time system used by the GALAXY programs. 

Contains information about the HELP command. 

Spooling program that sends IBM-batch- job files 
to remote IBM host and retrieves the output. 

Program that gives information to programs using 
IPCF. 

Program that maintains COBOL single-key indexed 
sequential files. 

Contains information about the ISAM program. 

A component of the debugging program for the 
TOPS-20 monitor. 

Program that loads the NIA20 microcode. 

The LCP subprocess to the OPR program. 

The LCP command table. 

Program that creates, maintains, and lists the 
contents of COBOL library files. 

Contains information about the LIBARY program. 

The COBOL object-time system (operating system 
interface) . 

Contains the COBOL library subroutines. 

Program that loads relocatable binary programs. 

Contains information about the LINK program. 

Translation RAM file for a 64-character line 
printer. Read by n-SETSPD. 

Translation RAM file for a 96-character line 
printer. Read by n-SETSPD. 

Program that controls output to the line printer. 

Run-time file for macros in MACSYM. 

The MACRO assembler. 

Contains information about the MACRO assembler. 

Contains system macros. 

Program that sends messages to users. 

Contains information about the MAIL program. 
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Table 3-2: STR:<SUBSYS> Files (Cont.) 



Programs 



MAILER.EXE 

MAKDMP.EXE 

MAKLIB.EXE 

MAKLIB.HLP 
MAKRAM.EXE 

MAKRAM.HLP 
MAKVFU.EXE 

MAKVFU.HLP 
MAPPER.EXE 

MDDT.REL 

MONSYM.REL 

MONSYM.UNV 
MOUNTR.EXE 
MSCPAR.UNV 

*NFT.EXE 
*NFT.HLP 
*NMLT20 

NORMAL. VFU 
OPR.EXE 

OPR.HLP 
ORION.EXE 

OVRLAY.REL 
PA1050.EXE 
PAT. EXE 



Explanation 



Program that receives mail from the MAIL program 
and places it in the appropriate mailbox. 

Program that produces a standard DUMP. EXE file in 
<SYSTEM>. 

Program that creates relocatable subroutine 
libraries. 

Contains information about the MAKLIB program. 

Program that creates a translation RAM file for 
line printers. 

Contains information about the MAKRAM program. 

Program that creates a vertical formatting unit 
(VFU) file. 

Contains information about the MAKVFU program. 

Program that loads the program-name cache. (Refer 
to Section 10.4, Improving Program Startup Time.) 

A component of the debugging program for the 
TOPS-20 monitor. 

Object file that contains monitor call symbol 
definitions. 

Contains symbol definitions for monitor calls. 

Program that mounts tapes and structures. 

A file of universal symbols used to build the 
MSCP component of the TOPS-20 monitor. 

DECnet file transfer program. 

Contains information about the NFT.EXE program. 

DECnet program that performs the network control 
program functions. 

Vertical formatting unit file for line printers. 

Program that the operator uses to interface with 
all jobs and devices on the system. 

Contains information about the OPR program. 

Program that processes messages sent by the OPR, 
MOUNTR, LPTSPL, QUASAR, EXEC, etc. programs. 

Overlay manager for the LINK program. 

The TOPS-10 Compatibility Package. 

Version of PA1050 that can be used in debugging. 
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Table 3-2: STR:<SUBSYS> Files (Cont.) 



Programs 



PHYPAR.UNV 

PLEASE.EXE 

PROLOG . UNV 

PTYCON.EXE 

PTYCON.HLP 
QMANGR.EXE 
QUASAR.EXE 

RDMAIL.EXE 

RDMAIL.HLP 
REAPER.EXE 

REAPER. HLP 
*RERUN.EXE 
*RERUN.HLP 
RETRFB.SPE 
RFB.EYE 

RMS. EXE 

RMSCOB.EXE 

RMSINI.REL 

RMSINT.R36 
RMS INT. UNV 
RMSUTL.EXE 
RSXFMT.EXE 

RSXFMT.HLP 
RUNOFF.EXE 
RUNOFF. HLP 



Explanation 



A file of universal symbols for TOPS-20 
input/output programs. 

Program that establishes a dialog with the 
operator. 

A file of universal symbols used to build the 
TOPS-20 monitor. 

Program that controls many jobs from a single 
terminal . 

Contains information about the PTYCON program. 

Program that manages the batch and print queues. 

Program that does the central queuing and 
scheduling for the batch system. 

Program that allows a user to read mail sent with 
the MAIL program. 

Contains information about the RDMAIL program. 

Program that marks files for migration to 
magnetic tape. 

Contains information about the REAPER program. 

Restarts COBOL programs. 

Contains information about the RERUN program. 

Contains SPEAR report templates. 

Contains internal definitions for the RETRIEVE 
function of the SPEAR program. 

RMS-20 used in Section of memory. 

RMS-20 used by COBOL V12B programs. 

Routine called by BLISS and MACRO programs to 
initialize RMS-20. 

Unsupported BLISS interface file for RMS-20. 

MACRO interface file for RMS-20. 

The RMS-20 file maintenance utility. 

Utility program used for converting TOPS-20 files 
to a format used by the front end and vice versa. 

Contains information about the RSXFMT program. 

Program that helps with text preparation. 

Contains information about the RUNOFF program. 
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Table 3-2: STR:<SUBSYS> Files (Cont.) 



Programs 



SCAPAR.UNV 

SCSTST.EXE 

SDDT.EXE 

*SELOTS.EXE 

SERCOD.UNV 

*SIX12.REL 

*SORT.EXE 

*SORT.HLP 

SPRINT.EXE 

SPROUT.EXE 

SPEAR.EXE 

SPRRET.EXE 

SPRSUM.EXE 

SYSJOB.HLP 

SYSTAP.CTL 

TCX.EXE 

TCX.HLP 

TERMINAL. HLP 

TOC.EXE 

TOC.HLP 
TV. EXE 
UDDT.EXE 
ULIST.EXE 

ULIST.HLP 
VERIFY.EXE 



Explanation 



A parameter file of symbols for 
inter-system communication routines. 



the 



SCA 



A program that tests SCA. 

DDT debugger for programs without a symbol table. 

Program that interfaces between the COBOL 
language and the COBOL object-time system 
(LIBOL). (It is used with versions of COBOL up to 
and including version 11.) 

Contains definitions for the SYSERR error codes. 

The BLISS debugger. 

Program that sorts files record by record. 

Contains information about the SORT program. 

Program that creates batch jobs from card input. 

Output spooler for card punch, paper tape punch, 
and plotter. 

Segment of SPEAR program. 

Segment of SPEAR program. 

Segment of SPEAR program. 

Contains information about the SYSJOB program. 

Control file that creates a system backup tape. 

A DIGITAL Standard Runoff index utility. 

Contains information about the TCX utility. 

Contains information about the TERMINAL command. 

A DIGITAL Standard Runoff utility for creating a 
table of contents. 

Contains information about the TOC utility. 

A character-oriented text editor. 

DDT debugger for programs with a symbol table. 

Program for printing information about 
directories and users. 

Contains information about the ULIST program. 

Program that is used during software installation 
to determine the integrity of files. It verifies 
checksums and version numbers of the .EXE files. 



WATCH.EXE J Program for observing system performance. 
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Table 3-2: STR:<SUBSYS> Files (Cont.) 



Programs 



WATCH. HLP 
*XPORT.REL 

XRMS.EXE 



Explanation 



Contains information about the WATCH program. 

Library containing the BLISS transportable I/O, 
memory, and string functions. 

RMS-20 for use from memory sections other than 
Section 0. 



NOTE 



All the .HLP files can be displayed using the HELP 
command; for example, the command @HELP WATCH displays 
the WATCH. HLP file. 



3.2.5 Restoring the Directory <SUBSYS> 

If the contents of <SUBSYS> are accidentally lost or destroyed, you 
can restore the directory from the TOPS-20 Installation Tape or your 
latest system backup tape. (Refer to Chapter 7 for information about 
creating system backup tapes.) Use the procedure below to restore the 
<SUBSYS> directory. If you have enabled tape drive allocation, use 
the MOUNT command instead of the ASSIGN command. (Refer to Section 
8.3 for information about using tape drive allocation.:) 

1. Mount the appropriate tape (in this example, it is on drive 
MTA0 : ) 

2. Give the following commands at your terminal. 

@ENABLE (CAPABILITIES) <RET> 
$ASSIGN (DEVICE) MTA0: <RET> 
$SKIP (DEVICE) MTA0: 4 FILES <RET> 
$RUN (PROGRAM) MTA0: <RET> 

DUMPER> TAPE (DEVICE) MTA0 : <RET> 

DUMPER> SKIP (NUMBER OF SAVESETS) 1 <RET> 

DUMPER> RESTORE (TAPE FILES) DSK* :<*>*.* .* (TO) <SUBSYS> 

<RET> 

DUMPER TAPE # 1 , , SATURDAY, 3-NOV-84 330 
LOADING FILES INTO STR:<SUBSYS> 
END OF SAVESET 

DUMPER> EXIT <RET> 
$ 
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3.2.6 <NEW-SYSTEM> and <NEW-SUBSYS> 

The first time you install the TOPS-20 software, the DLUSER program 
creates the directories <NEW-SYSTEM> and <NEW-SUBSYS>. They do not 
contain files. You can use these directories when a new release 
becomes available and you are updating the existing system. When 
DIGITAL distributes an updated monitor on the TOPS-20 Installation 
Tape, you restore the first two savesets from this tape to the 
directories <NEW-SYSTEM> and <NEW-SUBSYS> respectively. You use these 
directories until you feel comfortable with the new software. Should 
you have any problems with the new software, you can easily revert to 
using the old software. Appendixes A and B of the TOPS-20 KL Model B 
Installation Guide detail the procedures to update one software 
release to another. 

If you have no problems with the new monitor, and you are comfortable 
with it, copy all the files in the directory <NEW-SYSTEM> into the 
directory <SYSTEM> and all the files in the directory <NEW-SUBSYS> 
into the directory <SUBSYS>. You can now delete all the files in 
<NEW-SYSTEM> and <NEW-SUBSYS>. The directories <NEW-SYSTEM> and 
<NEW-SUBSYS> remain empty until a new version of the TOPS-20 software 
is distributed. 

NOTE 

After you copy the new files into the directories 
<SYSTEM> and <SUBSYS>, you cannot revert to the old 
system software unless you reinstall the system using 
the old monitor or backup tapes. 



3.2.7 <ACCOUNTS>„ <OPERATOR>, <SPOOL>, and <SYSTEM-ERROR> 

<ACCOUNTS> - After installation, the directory <ACCOUNTS> contains one 
file, SYSTEM-DATA.BIN. This file contains all the accounting system 
entries for each user. If the directory <ACCOUNTS> is destroyed, the 
accounting system creates a new SYSTEM-DATA.BIN file. 

After the first LOGIN on the system, the system creates the 
<ACCOUNTS>CHECKPOINT.BIN file. This file stores accounting entries 
for each user during the time the user is logged in. After a user 
logs out, the accounting data stored in CHECKPOINT.BIN is copied to 
the SYSTEM-DATA.BIN file. When the system comes up after a crash, the 
monitor examines <ACCOUNTS>CHECKPOINT.BIN to determine which users 
were logged in at the time of the crash, and stores the data in 
CHECKPOINT.BIN in SYSTEM-DATA.BIN. Therefore, users who did not log 
out in the normal fashion, because of a crash, are still charged for 
their log- in time. 

<OPERATOR> - The directory <OPERATOR> normally contains the file 
PTYC0N.LOG. This file usually contains a record of all the activities 
that occur under the operator jobs that are controlled by PTYCON. The 
directory <OPERATOR> may also contain files the operator needs to run 
the system. 
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<SYSTEM-ERROR> - The directory <SYSTEM-ERROR> contains the file 
ERROR. SYS. The ERROR. SYS file contains entries about system errors 
and is read by the system error recovery program, SPEAR. 



3.2.8 Other Useful Directories 

You may want to create additional directories for storing different 
versions of programs or text. Some useful directories are listed 
below. You should give these directories the proper protection number 
and make them files-only directories. 

Directory and File Protection 

Directories and files that are executed or read by the entire user 
community should not be given the default protection 777700, which 
allows no access. They should be given the directory protection 
777740 and the file protection 777752 or 777712. (Section 5.7 
describes directory and file protections.) 



<NEW> 



<OLD> 



The directory <NEW> can contain vers 
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The directory <OLD> can contain the old version 
of software as newer versions appear on <SUBSYS>. 
If programs or data do not work with new 
software, the user has a chance to correct the 
problems before the older software is no longer 
available. Users will find it convenient if you 
also define the system-logical name OLD: as 
PUB:<OLD>,SYS: , where PUB: is the public 
structure. 
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By creating the directories <NEW> and <OLD>, you gradually introduce 
new software to system users. When a new version becomes available, 
place it in the directory <NEW>. When the software has been in use 
awhile, move the version in <NEW> to <SUBSYS>, and the version in 
<SUBSYS> to <OLD>. Store the version in <OLD> on a system back-up 
tape,. Every time you change a version of the software, you should 
send a system-wide message to all users. 

<HELP> The directory <HELP> contains documents and help 

files that describe the system software. As 
different versions of software appear on 
<SYSTEM>, <NEW>, and <OLD>, you should make a 
list of changes incorporated in the new versions 
and place it in the directory <HELP>. You can 
move all files with the file type .HLP from 
<SUBSYS> to the directory <HELP>. The HELP 
command still works correctly if you define the 
system-logical name HLP: to be PUB:<HELP>,SYS : , 
where PUB: is the public structure. 

<REMARKS> The directory <REMARKS> contains messages from 
users to the operator. These messages are usually 
general system comments or complaints. When a 
user wants to send the operator a message that 
does not require an immediate response, he can 
send a message to the directory <REMARKS> using 
the MAIL program. (Refer to the description of 
the MAIL program in the TOPS-20 User Utilities 
Guide. ) A typical message may be a request for 
supplies, for example, LA36 paper or ribbon. 
Creating the directory <REMARKS> avoids constant 
interruptions to the operator from users issuing 
PLEASE requests. The operator can read the 
messages in <REMARKS> at a specified time each 
day, or simply when he has time. 



3.3 SYSTEM-LOGICAL NAMES 

I A logical name is a descriptive word used to establish a search route 
I to locate files. It can be up to 39 alphanumeric characters; however, 
it is usually three to six alphanumeric characters. Because logical 
names are used in place of device names, they always end with a colon. 
Logical names tell the system where and in what order to search for 
files. When a user types a logical name, the system searches the 
directories in the order they were defined or listed by the logical 
name. Although users can define logical names for their own use 
(refer to the TOPS-2 User's Guide ) , the logical names described here 
can be used by all users of the system. You can define system-logical 
names in the n-CONFIG.CMD file. 

I During installation, several system-wide logical names are defined by 

I the monitor, and may be overridden in the n-CONFIG.CMD file. They are 

I SYS:, defined as PUB:<NEW-SUBSYS>, PUB : <SUBSYS>; SYSTEM:, defined as 

I PUB:<NEW-SYSTEM>, PUB: <SYSTEM>; DEFAULT-EXEC:, defined as 

I SYSTEM: EXEC. EXE; and POBOX: , defined as the public structure. (PUB: 

I is the public structure.) You may decide to add other logical names to 

I aid users in accessing files. If you want the logical names to be 
permanent, place the definitions (using an editor) in the 

I <SYSTEM>n-CONFIG.CMD file on the public structure. 

I SYSTEM:, SYS:, DEFAULT-EXEC:, POBOX:, and some other frequently used 
system-logical names are explained below. 
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3.3.1 SYSTEM: 

The logical name, SYSTEM:, defines a search list that contains all the 
system programs and files that the system needs to operate. SYSTEM: 
I should always contain the directory <SYSTEM> on the public structure. 
If you are updating the system with a new monitor, the definition of 
SYSTEM: in the n-CONFIG.CMD file also contains the directory 
<NEW-SYSTEM>. For example, 

DEFINE SYSTEM: STR: <NEW-SYSTEM> , STR : <SYSTEM> 

I where: 

I 

I STR: is the name of the public structure. 



3.3.2 SYS: 

The logical name SYS: defines a search list that cpntains all the 
system programs a user may want to run. SYS: shouj.d always contain 
the directory <SUBSYS> and any other library directories that contain 
commonly used programs. If you are updating the system with a new 
monitor, the definition of SYS: in the n-CONFIG.CMD file also 
contains the directory <NEW-SUBSYS>. For example, 

DEFINE SYS: STR: <NEW-SUBSYS> , STR: <SUBSYS> 

I where: 

I 

| STR: is the name of the public structure. 

Be sure to set the protection on the library files in <SUBSYS> (or 
I <NEW-SUBSYS>) to 777740. This protection allows access by all users. 



3.3.3 NEW: 

The logical name NEW: defines a search list containing a directory 
that has new software, followed by the system-logical name SYS:. The 
definition for this, which you would put in n-CONFIG.CMD, is the 
following : 

DEFINE NEW: STR: <NEW> , SYS : 

With this system-wide logical name, the user can give; the command: 

@DEFINE (LOGICAL NAME) F,YS: (AS) NEW: <RET> 

Now, when the user runs a program, the system looks first in the 
directory STR:<NEW>, and then in the normal system search list SYS:. 
This way, the user always gets the most recent version of any program. 
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3.3.4 OLD: 

If you have old versions of programs, defining the system-logical name 
OLD: may be helpful to users. The usual definition of the logical 
name OLD: is: 

DEFINE OLD: STR:<OLD>,SYS : 

The definition OLD: has the same type of effect as the definition 
NEW:. If the user gives the command: 

@DEFINE (LOGICAL NAME) SYS: (AS) OLD: <RET> 

whenever he runs a program, he will get the oldest version available. 



3.3.5 HLP: 

If you want to keep programs and documentation in separate 
directories, you should store the documentation in <HELP>. The HELP 
command searches the directories identified by the logical name HLP:, 
so you must define the logical name HLP: to be the directory <HELP>. 

The definition of HLP: in n-CONFIG.CMD should be: 

DEFINE HLP: STR:<HELP> 



3.3.6 SERR: 

The logical name SERR: defines a search list that contains the system 
error file ERROR. SYS. The SERR: logical name tells the system to 
search the directory <SYSTEM-ERROR> for the ERROR. SYS file. This file 
may be used later to produce reports. 

The definition of SERR: in n-CONFIG.CMD should be: 

DEFINE SERR: STR: <SYSTEM-ERROR> 
where: 

STR: is the name of the public structure. 



3.3.7 DMP: 

When the system is re-booted after a crash, the file DUMP. EXE is 
overwritten with a copy of memory. Upon system startup, the n-SETSPD 
program copies the contents of DUMP. EXE to the DMP: DUMP. CPY;P770000 
file. System crashes cause DUMP. EXE to be overwritten, but new 
versions of DUMP.CPY accumulate. To keep the public structure clear 
of DUMP.CPY files, the definition of DMP: in the n-CONFIG.CMD file 
should be: 

DEFINE DMP: STR: <DIRECTORY> 

The structure and directory are your choice; you should not specify a 
filename. Versions of DUMP.CPY hereafter accumulate in the defined 
area. 
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In CFS configurations, systems should not share a common 

DMP: definition, because this could lead to confusion about which dump 
came from which system. 



3.3.8 DEFAULT-EXEC: 

The logical name DEFAULT-EXEC: defines a search list that points to 
the TOPS-20 Command Processor (EXEC). When users log in or give the 
PUSH command, the EXEC program is activated. Some experienced users 
may choose to run their own copies of the EXEC, not the standard 
system version. Such users can define DEFAULT-EXEC: to be the file 
name for their private EXEC, and can take advantage of this feature 
after giving the PUSH command. This command must be given at the EXEC 
level, while in batch or interactive mode. PUSH commands issued from 
other program levels may invoke the standard system version, unless 
the program has been written to use DEFAULT-EXEC: if it is defined. 
By default, DEFAULT-EXEC: is defined as SYSTEM: EXEC. EXE. 

Refer to the DECSYSTEM-20 Technical Summary and the TOPS-20 Commands 
Reference Manual for more complete information on the EXEC. 



3.3.9 POBOX: 

The logical name POBOX: points to the structure where users' mail 
files reside. Mail sent to users goes to the MAIL. TXT files in their 
directories on the structure POBOX:. Therefore, a directory must be 
created on that structure for each user. By default, POBOX: is 
defined as the public structure. You can redefine POBOX: in the 
n-CONFIG.CMD file to be any structure you choose. 

By redefining POBOX:, you can prevent users* mail files from filling 
up the public structure. 

In CFS-20 configurations, redefining POBOX: is especially useful. 
You can define POBOX: to be the same structure for all systems, 
establishing a central location for all mail files in the 
configuration. Then, no matter what system users log onto, they are 
automatically directed to this one area when they give commands to 
access their mail. They do not have to spend time logging onto 
various systems to access mail that would otherwise have been sent to 
a public structure. To set up this central location, the same DEFINE 
command should be entered in each system's n-CONFIG.CMD file. Refer 
to Chapter 12, The Common File System, for further information on 
CFS-20. 
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3.3.10 NRT: 

The logical name NRT: (Network Remote Terminal) is applicable only if 
your system has DECnet communications software. When a user issues 
the SET HOST command to connect to a remote system, the CTERM-SERVER 
communications program is run by default. If the remote node does not 
support CTERM, the host system tries to connect the user again, this 
time using the program defined by NRT:. 

Examples 

1. For TOPS-20 to TOPS-20 communications, give the following 
definition: 

DEFINE NRT: SYS : SETHOST. EXE 

2. For multi-operating system DECnet communications, you can 
specify the HOST program (located on the TOPS-20 tools tape): 

DEFINE NRT: HOST. EXE 



3.4 CONSOLE FRONT-END FILES 

The console front-end computer consists of a PDP-11 with 28K 16-bit 
words of memory. When the system is brought up for timesharing, the 
front-end monitor, RSX20F, is loaded in the PDP-11 memory and started. 
I The TOPS-20 monitor is loaded in KL10 main memory and started. Thus, 
you have two computers working together. Both computers have their 
own monitor and related software. 

The front-end file system consists of the RSX20F monitor and related 
programs (tasks) and files. During software installation, these 
front-end files are transferred from floppy disks to a special area on 
the system structure unless an RP07 is being used as the system 
structure. If an RP07 is being used as the system structure, only the 
files on the TOPS-20 Installation Tape will be placed on the RP07. 
The front-end files, on the floppy disks, must be placed on a 
dual-ported RP04 or RP06 disk drive attached to the PDP-11 front end. 
(Refer to the TOPS-20 KL Model B Installation Guide for the procedure 
for creating the front-end file system when using an RP07 disk drive 
as the system structure.) 

The area the front-end files are placed on is called the FRONT-END 
FILES area, or FILES-11 area. Once this area has been set-up, there 
is normally no need to get these files again from floppy disks. The 
floppy disks used to install the system become backup devices in case 
the public structure is destroyed, or in the case where an RP07 is 
being used as the system structure, they can be used to recreate your 
front-end file structure. It is a good idea to make an extra copy of 
your installation floppies in the event one of your original floppies 
is destroyed and you need to restore the FRONT-END FILES area. Refer 
to Chapter 7, System Backup Procedures, for a description of the COP 
program that is used to copy floppy disks. 

As previously stated, the front-end files must always be placed on a 
I dual-ported RP04 or RP06 attached to the PDP-11 front end. This 
allows the front-end processor to access these files while the main 
processor accesses TOPS-20 files on the same or different disk packs. 
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The RSX20F monitor and its related programs do the following: 

• Control input/output and communications devices. 

• Interface with the main computer. 

• Load the TOPS-20 monitor at system startup, and reload 
TOPS-20 if a crash occurs. 



• Report system errors to TOPS-20. 

• Perform system diagnostic functions. 



Table 3-3 lists the programs and 
area, with a brief description o 
are programs that can be run unde 
with the type MCB contain the mic 
files with the type EXB are boo 
TOPS-20 monitor; and files with 
information about system errors, 
system error recovery program, S 
6, console front-end filenames 
indicate the versions of the 
F11ACP.TSK;1505. 



files located in the FRONT-END FILES 
f each. Files with the file type TSK 
r the front-end monitor RSX20F; files 
rocode for the host processor (KL10); 
tstrap programs used to load the 
the type CMD are programs that record 

This information i$ read by the 

PEAR. Beginning with TOPS-20 Version 

include edit-level; numbers that 

particular programs, for example, 



Table 3-3: Console Front-End Files 



File 


Contents or Function 


BF16N1.A11 


MOS memory-timing RAM file. It is a nonexecutable 
file containing MOS memory data. 


BF64N1.A11 


Timing file for 64K RAM chips. 


BOO. TSK 


Used to boot RSX20F. 


BOOT. EXB 


The central processor disk bootstrap program that 
boots TOPS-20 from disk. 


CLOCK.CMD 


Saves contents of memory locations fpr diagnosing 
errors that are purposely induced by Field 
Service. 


COP. TSK 


Copies the contents of floppy disks. 


CRAM. CMD 


Saves contents of memory locations for diagnosing 
CRAM parity errors. 


DEX.CMD 


Saves contents of memory locations for diagnosing 
Deposit Examine failures (PI level interrupt) . 


DMO. TSK 


Dismounts a front-end device and allows a reboot. 


DRAM. CMD 


Saves contents of memory locations for diagnosing 
DRAM parity errors. 


EBUS.CMD 


Saves contents of memory locations for diagnosing 
EBUS parity errors. 


FMPAR.CMD 


Saves contents of memory locations for diagnosing 
fast memory parity errors. 
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Table 3-3: Console Front-End Files (Cont.) 



File 



F11ACP.TSK 
HALT.CMD 

INI. TSK 

KLDISC.TSK 

KLI.TSK 

KLRING.TSK 

KLX.MCB 

KPALV.CMD 

LOGXFR.TSK 

LOOP.CMD 

MIDNIT.TSK 
MOU.TSK 
MTBOOT.EXB 
PARSER. TSK 

PIP.TSK 
RED. TSK 

RSX20F.MAP 
RSX20F.SYS 
SAV.TSK 

SB0.CMD 

SB1.CMD 

SETSPD.TSK 
TIMEO.CMD 

TKTN.TSK 



Contents or Function 



File handler for front-end disk files. 

Saves contents of memory locations for diagnosing 
KL halt errors. 

Initializes a front-end files area. 

Provides the KLINIK line disconnect service. 

KLINIT program for initializing the central 
processor (KL20) . Loads microcode, configures 
cache and main memory, loads bootstrap. 

Provides the KLINIK line ring service. 

KL10 microcode file. 

Saves contents of memory locations for diagnosing 
keep alive cease errors. 

Transfers the PARSER.LOG file to the TOPS-20 
error file. 

Saves contents of memory locations for diagnosing 
errors causing the KL to hang but not crash. 

Updates the time of day through midnight. 

Mounts a device for use with the front end. 

Boots a TOPS-20 monitor from magnetic tape. 

The front-end command parser (prompts PAR>) . The 
primary means of access to front-end programs. 

Front-end program for file transfer. 

Tells the system where to look for the front-end 
files device, SY0:. 

Contains symbolic definitions for RSX20F. 

Virgin image of front-end monitor (RSX20F) . 

Saves the front-end monitor and bootstrap on 
disk. 



Helps field 
problems. 

Helps field 
problems. 



service diagnose SBUS-related 
service diagnose SBUS-related 



Sets system parameters, such as line speeds. 

Saves contents of memory locations for diagnosing 
protocol timeout errors. 

Terminates tasks, reports errors, and requests 
J reloads. 
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Table 3-3: Console Front-End Files (Cont.) 



File 



T20ACP.TSK 



UFD.TSK 



ZAP.TSK 



Contents or Function 



Interfaces between front-end and TOPS-20 file 
systems. 

Sets up user-file directories in the front-end 
files area. 

Makes binary modifications to task images. 



3.5 TAILORING THE BATCH SYSTEM 

Most installations use the parameters and defaults in the distributed 
version of the batch system. However, you can modify some of these 
parameters if required by the batch processing procedures at your 
installation. 

DIGITAL distributes a program with the TOPS-20 software that allows 
you to tailor the standard batch system to the requirements of your 
installation. This program, called GALGEN.EXE, is located in the 
directory <SUBSYS> on the system structure. You can run GALGEN at the 
time the system software is installed or at a later date. In either 
case, you must have a working batch system before you can generate a 
new one using GALGEN. This means if you are installing the system, 
you must first install the batch system that is distributed with every 
new version of the TOPS-20 software (on the software installation 
tape). You can then run the GALGEN program and tailor the batch 
system before it becomes available for general use. 

If you tailor the batch system at a later date, you can run the GALGEN 
program with users logged in. However, for safety reasons, the system 
should be stand-alone during the critical phase of stopping the old 
batch system and starting the new one. The batch queues, however, 
need not be empty. That is, batch jobs can be waiting to be processed 
at the time you bring the system down. 

The TOPS-20 KL Model B Installation Guide contains the procedures for 
running the GALGEN program. 



3.6 CHECKING THE SOFTWARE (UETP) 

After the system software is installed, you or the Software Specialist 
can run the User Environment Test Package (UETP). UETP is a 
collection of programs, data files, and batch control files designed 
to allow you to test the integrity of various system elements. In 
addition to testing that the hardware has been properly installed, 
UETP ensures that the TOPS-20 Operating System is running and that the 
languages you have selected for your operation are available. 

UETP creates a moderate load on the system, consisting of various 
defined procedures that closely resemble the load in an actual 
operation. Later, you may want to tailor UETP to test a software load 
that more closely resembles your particular system's use. 

The TOPS-10/TOPS-20 User Environment Test Package Reference Manual 
describes UETP, the individual component tests, typical message 
information, and the procedures for adding new tests. 
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CHAPTER 4 
CREATING STRUCTURES 



4,.l OVERVIEW 

One of the first decisions you must make about your new (or upgraded) 
installation is what type of disk storage environment best suits your 
needs. Some of the considerations that determine your decision are: 

• How large will the data base be? 

• How many users will be using the system? 

• How experienced will these users be? 

• Will there be a full-time operator? 

• How often will you run diagnostics and how critical is it 
that the system remain available during this maintenance? 

• Must all files be available to all users at all times during 
system operation? 

• Are multiple systems part of a CFS configuration? Refer also 
to Chapter 12, The Common File System. 

The mountable structure facility of TOPS-20 provides several options 
for making this decision. The option you choose depends on the 
answers to the previous questions and the number of disk packs and 
drives that are available. For example, if your installation has a 
number of disk packs and two or more drives, you can store data and 
program files on different structures. 

A structure is a collection of data and program files contained on one 
or more disk packs and referenced under one name. 

When you install your software, you create a structure known as the 
public structure (sometimes called the system structure). All packs 
in this structure remain on-line at all times during system operation. 
If your public structure does not encompass all of your available 
drives you can create and mount other structures. 

Sections 4.2 through 4.8 describe the public structure and how you can 
best utilize your disk resources and create and use other structures. 
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4.2 THE PUBLIC STRUCTURE 

Sections 4.2.1 and 4.2.2 provide an overview of what the public 
structure is, including its relationship to the system and its 
contents. 



4.2.1 What Is the Public Structure? 

The public structure is the most important structure on^ your system. 
It is created and brought on-line at system installation when you 
answer the appropriate questions in the installation dialog. (R ^? r 
to the TOPS-20 KL Model B Installation Guide .) The name of the public 
structure can be up to six characters. 

The public structure can be one or more disk packs, depending on the 
configuration of your system and your disk drive resources. You may 
use one or more RP04, RP06, or RP07 disks as the public structure; the 
maximum number of disks per structure is given in Table 4-4. You may 
NOT use an RA60, RA81, or RP20 as the public structure. 

While installing the software, you copy the console front-end files to 
the public structure pack that is mounted on a dual-ported drive 
(usually drive 0). The dual port allows the front-end processor and 
the central processor to access the data on the public structure. 
However, if you are using an RP07 as the public structure, you must 
reserve space for the front-end files on an RP04 or RP06 disk that is 
dual-ported to the PDP-11 front end. If the disk structure containing 
the front-end files has multiple packs, the first pack of the 
structure must be permanently mounted on the dual-ported drive. 

All disk packs in the public structure must be online at all times, 
because this structure contains all the programs, files, and swapping 
area that the system needs to operate. The structure also contains 
all user directories necessary to support users logging into the 
system. If the file system is destroyed on the public structure, or 
if a drive that contains all or part of the structure malfunctions, 
the system halts. Refer to Chapter 9 in this manual and to the 
TOPS-20 Operator's Guide for the steps that you and the operator must 
follow if you have problems with the file system or if a drive goes 
down. 

You can have another structure online that is capable of being used as 
the public structure. This structure must have a unique name, 
however, at least while it is mounted. (Section 4.5.2 provides 
information about mounting structures having the same name.) Section 
4.5.5 discusses why you would have such a structure. 

If you are using CFS-20 software, refer to Chapter 12, The Common File 
System, for additional information on the public structure. 



4.2.2 The Contents of the Public Structure 

The following list provides an overview of the contents of the public 
structure: 

j 1. The default TOPS-20 command processor, EXEC, which is usually 
| found in <SYSTEM> or <NEW-SYSTEM>. 

2. A <ROOT-DIRECTORY> (Section 3.2.1) that points to the 
| location on disk of all first-level directories on the public 

| structure, including the special system directories. 
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3. All the files in the directories <SYSTEM> and <SUBSYS> 
(Sections 3.2.2 and 3.2.4). 

4. The directories <NEW-SYSTEM>, <NEW-SUBSYS>, <ACCOUNTS>, 
<OPERATOR>, <SYSTEM-ERROR> and <SPOOL> (Sections 3.2.6 and 
3.2.7) . 

I 

I 5. The front-end monitor (RSX20F) and the console front-end 
I files (Section 3.4). This normally appears in the 

I <ROOT-DIRECTORY>. If you are using the RP07 as the public 

structure, the front-end file system must reside on either an 

RP04 or RP06 dual-ported disk drive. 

6. The required swapping area. The size of this area depends on 
the TOPS-20 monitor you are using. For example, 2060-MONMAX 
uses up to 15,000 pages of disk space for swapping. (Refer 
to Section 4.7 for a description of the swapping area.) 

7. A HOME block that contains the following parameters: 

• the structure's physical name 

• the number of disk packs in the structure 

• which pack this is in the structure 

• the address and number of pages used for the front-end 
file system (usually 950) 

• the address and number of pages set aside for swapping 

• the address of the <ROOT-DIRECTORY> and its backup copy 

• the serial number of the KL CPU to be booted from the 
structure 

8. A directory for every user who requires access to the system. 
Users must log into a directory on the public structure to 
use the system. Afterwards, they can mount and connect to a 
different structure and directory. 



4.3 ONE-STRUCTURE SYSTEMS 

A one-structure system consists of a single structure, the public 
structure, which is always on-line. All packs in the structure must 
be on-line for the system to operate. 

Usually, a one-structure system has only one or two disk drives. 
Smaller TOPS-20 installations choose to keep all their directories and 
files on one structure for some of the following reasons: 

• It is the simplest system. 

• It is the easiest system to maintain. 

• There is no requirement to physically remove packs from the 
drives, for example, for security reasons. 

• The majority of users are inexperienced. 

• All files are available at all times, and thus are easy to 
access. 
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• A full-time operator may be unnecessary. 

• There is only one disk drive (only one structure supported) . 

Chapter 5 describes the methods you can use to create and maintain 
directories on your one-structure system. 

4.4 MOUNTABLE STRUCTURES 

If the public structure does not encompass all available, disk drives, 
you can create and mount other structures on the unused drives. These 
"mountable" structures are created using the CHECKD program. The 
TOPS-20 Operator' s Guide describes creating structures with CHECKD. 

NOTE 

The public structure is the only structure created at 
installation time. All other structures are created 
(using the CHECKD program) and brought on-line during 
system operation. 

4.4.1 Differences Between Mountable and Public Structures 

Unlike the public structure, a mountable structure can be mounted and 
dismounted during timesharing. Also, it need not contain a front-end 
file system. Therefore, a mountable structure does not have to reside 
on a dual-ported disk dr.ive. Although a mountable structure has its 
own <ROOT-DIRECTORY> and directory system, a user cannot log into a 
mountable structure, but must log in as a user on the public 
structure. A user can then mount a different structure and connect to 
directories. Table 4-1 summarizes the differences between a mountable 
and public structure. 

4.4.2 Similarities Between Mountable and Public Structures 

There are, however, many similarities between the public structure and 
mountable structures. Both contain user directories and files. A 
mountable structure can have a front-end file system, and can be used 
in place of the public structure to load the system for timesharing. 
A mountable structure is created with the eight special directories 
(mentioned in Chapter 3) as for a public structure. Likewise, a 
mountable structure has a HOME block that contains information such as 
the name of the structure and the number of disk units in the 
structure. These and other similarities are summarized in Table 4-2. 
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Table 4-1: Differences Between Mountable and Public Structures 



Public Structure 



Always up during timesharing 

Has a front-end file system 
(unless an RP07) 

Resides on a drive that is dual 
ported with the front-end 
computer (unless an RP07) 

Used for logging into the 
system 

Belongs to the system 

Has the <SYSTEM>, <SUBSYS>, 
<ACCOUNTS>, <OPERATOR>, 

<SYSTEM-ERROR>, and <SPOOL> 
directories 



Must contain a swapping area 



Mountable Structures 



Can be mounted and dismounted 

Need not have a front-end file 
system 



Need not reside 
dual-ported disk drive 



on 



Cannot be used for logging into 
the system 

Can belong to a private user 

Need not have these directories 
unless the structure will be 
used as the public structure; 
can be deleted from the 
structure 

Need not contain a swapping 
area unless the structure is to 
be mounted as the public 
structure 



Table 4-2: Similarities Between Mountable and Public Structures 



Public Structure 



Has a HOME block 

Has a front-end files area 
(unless an RP07) 

Is used to load the system 



Contains system files 

Has a <ROOT-DIRECTORY> 

Contains user files 

All packs must be on-line for 
the system to operate 



Mountable Structures 



Has a HOME block 

Can have a front-end files area 

Can be used to load the system 
if the proper file areas and 
files have been established 

May contain system files 

Has a <ROOT-DIRECTORY> 

Contains user files 

All packs in the structure must 
be on-line to use the structure 



4.5 MULTIPLE-STRUCTURE SYSTEMS 

A multiple-structure system consists of a public structure and one 
or more additional structures. Figure 4-1 illustrates a system with 
three disk drives and two structures. The two-pack public structure 
MASTER: must be online during timesharing. The one-pack mountable 
structure ADMIN: can be removed during timesharing. Another 
one-pack structure can be mounted in its place. 
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UNITO 



UNIT 1 



UNIT 2 






STRUCTURE MASTER: 



STRUCTURE AOMIN: 



Figure 4-1: System with 3 Disk Drives and 2 Structures 

Using Figure 4-1, suppose you want structure ADMIN: to remain 
on-line at all times during system operation. The structure is 
automatically mounted if you turn on the drive thatj. contains the 
structure before the system is brought up. The TOPS-20 Operator's 
Guide describes mounting structures automatically. 

In addition to the public structure and perhaps another permanent 
on-line structure, you may choose to keep one or more disk drives 
available for users to mount and dismount "private" packs during 
timesharing . 

Figure 4-2 illustrates a system with three disk drives and three 
one-pack structures, the public structure MASTER:, ADMIN:, and 
PROG : . 



UNITO 



UNIT 1 



UNIT 2 





STRUCTURE 
ADMIN: 




Figure 4-2: Three-Structure System 

In this example, MASTER: contains all the directories necessary to 
support log-ins. ADMIN: contains the same, a superset, or a subset 
of the same directories as those on MASTER: and remains online at 
all times during system operation. The drive that contains PROG: 
is used for short-term mounting of different one-pack structures. 
PROG: remains online only for the time it is needed. 

I There can be up to 32 structures online at one time. 

Several of the advantages in a mountable structure environment are: 

• Some users or groups of users may require a structure 
exclusively for their use. They can 'own' or possibly pay 
for the use of certain structures. 
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• Service engineers can mount their own pack on the 
short-term drive and perform some diagnostics without 
disturbing normal system operation. 

• Creating structures on mountable packs provides additional 
security to that already within the system. For example, 
you can create a structure that contains highly 
confidential data, remove it from the drive(s) when you are 
done with it, and lock it in a security cabinet or safe. 
At the end of the day, the operator locks up any 
confidential structures. 

• In this type of environment, you are not limited in the 
size of your system's data base. You can create as many 
structures as you have disk packs to contain them, and you 
can mount as many at one time as your system can support. 

The principal disadvantages of using mountable structures are the 
need for scheduling both access to the data and operator coverage to 
install and remove packs on the drives, as described in Section 
1.2.2, Mountable Structure Sign-Up Log. There is also some risk 
that packs will be damaged during handling. 

After the system is operating and structures have been created, the 
operator responds to requests from users to mount and dismount 
structures. Section 4.5.5 describes how to place user directories 
on your mountable structures to obtain maximum availability to 
priority jobs. 



4.5.1 Choosing Structure Names 

Each device on the system has a name, called the physical device 
name, which is used when giving commands to the software. Unlike 
the generic device name that applies to a class of devices, for 
example: TTY:, DSK:, LPT:, the physical device name applies to a 
particular device on the system; for example, TTY6: and LPT0:. The 
physical device names for disks are structure names. A structure 
name can be from one to six alphanumeric characters of your choice, 
and, like other device names, must be followed by a colon. The 
colon indicates to the software that a device is being used and not, 
for example, a file. 

It is important to carefully assign a unique name to each structure 
that you create. Section 4.5.2, Mounting Structures Having the Same 
Name, explains why this precaution avoids confusion for users if an 
operator is unavailable during timesharing. 

Because structure names are used in the device field (dev:) of a 
file specification, you should not create any structures with the 
same name as a defined (or valid) device name. Table 4-3 lists 
device names that may be defined in your system. 

For the same reason, avoid naming a structure with a defined logical 
name, for example, SYS:, SYSTEM:, NEW:, OLD:, HLP:, etc., because 
the system searches the list of defined systemwide logical names 
before device names. (Refer to Section 3.3 for a description of 
logical names.) 

Refer to Chapter 12, The Common File System, for structure-naming 
considerations in a CFS environment. 
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Table 4-3: Sample Device Names 



DSK: 










CDP: 


MTAn: 










FEn: 


MTn: 










TTY: 


LPT: 










TTYn: 


LPTn: 










PTYn: 


PLPTn: 










NUL: 


CDR: 










PLT: 


PCDRn: 










PLTn: 


PCDPn: 










DCN: 


TCP: 










SRV: 


Where n 


is 


the 


un 


it 


number of the device. 



To avoid duplication, you can get a list of all structure names known 
to the system by giving the operator command, SHOW STATUS STRUCTURE. 
These structures do not have to be online. Their presence in the 
listing indicates that they were previously specified in a SET 
STRUCTURE command, or once mounted on the system. 



4.5.2 Mounting Structures Having the Same Name 

A situation may arise requiring you to mount a structure that has the 
same name as a structure that is already online. Perhaps another 
installation has requested that you mount its public structure (named 
PUBLIC:) for testing purposes, but you already have a structure named 
PUBLIC: online. Because the system notices ambiguous structure 
names, you must mount the structure under a different name. 

Each structure that is mounted is identified with two names: the 
physical identification and the alias. Usually, these names are the 
same. The physical identification is the actual structure name 
written in the HOME block of that structure. The alias is the name 
that you use to reference the structure while it is mounted. After a 
structure is mounted, it is known only by its alias. The MOUNT 
command is used to mount a structure and give it an alias different 
from the physical identification. This allows two or more structures 
with the same physical name to be mounted simultaneously. The system 
distinguishes them by their different aliases. (The TOPS-20 
Operator' s Guide describes this procedure.) 

Note that the structures must be mounted one at a time. That is, 
structures cannot be online simultaneously before the MOUNT command is 
given. One of the structues must be mounted first. It may be 
necessary to power down disk drives and bring them up 4gain. 
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4.5.3 Maximum Size of Structures 



The maximum size of a structure is approximately 805,680 pages. A 
structure of this size requires 3 RP20 disk drives (5 spindles). 

Structures of the maximum size, however, may not be practical for your 
installation. Smaller structures enhance the reliability and 
availability of the system. Remember that you can have up to 32 
structures on-line at one time. 

Also, if a structure is contained on more than one disk pack, the 
packs and drive units for that structure must all be the same type, 
that is, either all RP04s, RP06s, RP07s, RP20S, RA60s, or RA81s. For 
example, 



NOT SUPPORTED 




STRUCTURE 
ADMIN; 



SUPPORTED 



RP0<1 



STRUCTURE 
ADMIN: 



MR-S-534-80 



I Table 4-4 shows the maximum structure size using RP04, RP06, RP07, 
I RP20, RA60, and RA81 disk drives. For all drive types, there can be 
I 12,000 directories per structure and 5,000 files per directory. 

NOTE 

The number of directories per structure and files per 
directory that can be created is approximate. This is 
because the disk space needed to create a directory or 

I file varies according to the lengths of the names 

I chosen for directories and files. 



Table 4-4: Maximum Size Structures 



Type of 
Disk Drive 


Max. Mo. Packs 
Per Structure 


No. Pages 
Per Pack 


RP04 


6 


38000 


RP06 


3 


76000 


RP07 


1 


216376 


RP20 


5 


201420 


RA60 


6 


90516 


RA81 


5 


200928 
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4.5.4 Increasing the Size of Structures 

You can add more disk packs to increase the size of a mountable 
structure (not the public structure) during timesharing. To do this, 
you must: 

• Dump the entire file structure onto magnetic tape using the 
DUMPER program 

• Run the DLUSER program 

• Run the CHECKD program, specifying the new configuration, to 
re-create the structure 

• Restore all the directories and files from magnetic tape 
using the DUMPER program 

IMPORTANT 

If possible, re-create the structure and restore the 
files to a different set of packs from the structure 
that you dumped. This precaution ensures that you do 
not lose any valuable data should you have problems 
reading the tape back to disk. That is, you still 
have the original structure intact and can rerun 
DUMPER and copy the structure to another tape. 

To increase the size of the public structure, you must shut down the 
system and follow the installation procedure for bringing up this 
structure with more disk packs. Refer to Chapter 9, System 
Problems/Crashes, and to the TOPS-20 KL Model B Installation Guide . 



4.5.5 Setting Up Structures for Maximum Availability 

Before you create structures and place user directories on them, you 

should determine which users must be on the system at all times. 

Place these users' directories and files on the public structure, or 

I on another structure that is always available during timesharing. 

Divide the remaining users of the system by priority, and place their 

directories and files on the other structures. Although these users 

have log-in directories on the public structure, their large working 

area where they create and store files is on the other on-line 

I structures. You may want to help users set up their LOGIN.CMD and 

I BATCH.CMD files so that they can mount, connect, and access the 

I appropriate directory on the structure where their files are located, 

I if it is not the public structure. Dividing users into categories and 

placing them on structures accordingly ensures that the failure of one 

disk drive does not prevent the most important useirs from using the 

system. For example, if the drive that contains ADMIN: goes down, 

you can remove the ADMIN: pack from the broken drive, and mount it on 

another drive that contains a less critical structure. 

Also, on-line disk diagnostics can be performed during timesharing. 
Sometimes, the service engineer can dismount a non-critical structure, 
mount the maintenance pack, and perform preventive maintenance or 
trouble-shooting with only a portion of the user comrriunity off-line. 
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To increase system availability, you can create another public 
structure for backup using the CHECKD program. After you create this 
structure, you should follow the procedures in your software 
installation manual for creating the front-end files area. The 
TOPS-20 Operator' s Guide describes using the CHECKD program to create 
a backup public structure. If you have problems with the primary 
public structure, having a second public structure available allows 
you to resume timesharing without reinstalling the system. 

The backup public structure can be mounted and online at all times 
under another name, or it can be kept in storage and mounted as a 
backup if the regular public structure is destroyed. If the backup 
public structure is kept in storage, the operator must update the 
structure periodically with the System Backup Tape and the latest 
incremental dumper tapes. (Chapter 7, System Backup, describes 
creating and using your System Backup Tape and incremental tapes.) 
Occasionally updating your backup public structure (in storage) keeps 
it reasonably up-to-date. 

If you keep your backup public structure online at all times, and you 
have important files that are constantly accessed by the user 
community, you can improve your system performance by placing these 
I files on the backup public structure. Now your swapping area and the 
I files that you access frequently are not on the same disk. This 
procedure is useful with any structure that you keep on-line at all 
times. 

I If multiple systems are part of a CFS configuration, refer to Chapter 
I 12, The Common File System, for further discussion of placement of 
I files and user directories. 



4.5.6 Taking Structures Off-Line 

When a structure must be taken off-line, the operator should notify 
users that it will be dismounted at a certain time. Users should give 
the DISMOUNT command for the structure before the specified time. If 
the users do not cooperate, the operator can dismount the structure 
(via the DISMOUNT command to OPR) without leaving files in an unknown 
state. Files that are open simply become inaccessible, and the user 
who had the files open receives an error. 

For information on dismounting structures in a CFS environment, refer 
to Chapter 12, The Common File System. 
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4.5.7 Mounting Structures from Another Installation 

If you mount a structure from another installation/ or perhaps a 
structure that contains confidential data, some of the user names on 
this structure may match the user names on your public structure. You 
must mount this structure in what is called a FOREIGN state, to avoid 
the mishap of your users accessing directories that do not belong to 
them. The same is true if you bring one of your structures to another 
installation. You should have the operator at the installation SET 
the structure FOREIGN and then mount it. Figure 4-3 illustrates this 
concept. 



YOUR INSTALLATION 

iQ iQ 



PROG: 




DOMESTIC 




Figure 4-3: Domestic and Foreign Structures 



A structure is brought online in one of two states, DOMESTIC or 
FOREIGN, according to the setting that the operator last specified for 
this structure with the SET STRUCTURE command. The system uses the 
FOREIGN state as the default if a SET STRUCTURE command has never been 
given for this structure. The structure remains in the specified 
state until the operator changes the state with the SET STRUCTURE or 
the UNDEFINE command. Note that the setting is unchanged across 
system crashes and reloads. 



You should bring a str 
directories on that str 
those on the public struct 
a given directory name 
Conversely, you should bri 
directories on that str 
same people as those on th 
who is logged into a direc 
an identically named direc 
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for the owner, which i 
into the public structure 
directory with an identic 
associated password. 



ucture online as DOMESTIC only if the 
ucture were created for the same people as 
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e public structure. This is because a user 
tory on the public structure is the owner of 
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command to that directory without giving a 
ectory protection allows this type of access 
s the usual case). Howevejr, a user who logs 
and gives the CONNECT or ACCESS command to a 
al name on a FOREIGN structure must give the 
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4.6 SHARING STRUCTURES (DISK DRIVES J BETWEEN TWO SYSTEMS 

If you have two DECSYSTEM-20 1 s and one or more structures that contain 
data common to both of these systems, you may want to set up your 
system to share disk drives alternately. For example, you could allow 
System A to use the drive that contains structure ADMIN: in the 
morning and allow System B to use this structure on the same drive in 
the afternoon. THE SYSTEMS CANNOT, HOWEVER, ACCESS THE DRIVE AT THE 
I SAME TIME . [Refer to Chapter 12, The Common File System, for the 
I exception.) Also, if one of your systems goes down, you can still use 
the drive that is connected to both systems. 

A drive that is to be shared by two systems must be supported by both 
systems. For example, you cannot connect an RM03 disk drive to a 
DECSYSTEM-2020 and a DECSYSTEM-20 65 because the 2065 system does not 
support RM03s. Also, the shared drive must be dual-ported. Your 
field service representative must make the appropriate connections 
from each DECSYSTEM-20 to a port on the disk drive. Be sure to have 
the field service representative tell you which system is connected to 
which port on the drive. Figure 4-4 illustrates this connection. 



Duat-Ported 
DRIVE 



DECSYSTEM20 



DECSYSTEM-20 



FRONT-END 



MH-S-53S-80 



Figure 4-4: Shared Disk Drive 

The port switch on this drive must be in either the A or B position, 
unless the systems are part of a CFS configuration. Otherwise, 
TOPS-20 will not permit either system to access the disk while it 
in the A/B position. Error messages will be generated. 



is 



To use the drive, place the port switch in the position that 
corresponds to the first system that is using the drive (A or B) . The 
operator mounts a structure using the normal procedure. After the 
first system is no longer allowed to use the drive, the operator gives 
the DISMOUNT command for the structure. 

To use the drive on the second system, the operator leaves the pack on 
the drive (if you are using the same structure), turns the drive 
off-line, changes the port switch to the corresponding system, and 
turns the drive back on. Then, the operator (or a user) gives the 
MOUNT command to mount the structure on this system. The system 
automatically recognizes that another drive is on-line and mounts the 
structure. 
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4.7 DETERMINING SWAPPING SPACE ON THE PUBLIC STRUCTURE 

Sections 4.7.1 and 4.7.2 describe what swapping space is and how to 
determine the amount of swapping space that you should allocate for 
your system. 



4.7.1 What Is Swapping? 



The number of 
simultaneously 
size of the memo 
memory physical 
resides in main 
that is not curr 
may necessitate 
program or data 
the swapping are 
storage space on 



user processes that can fit into: main memory 
depends on the size of the individual processes, the 
ry-resident portion of the monitor, and the size of 
ly available. (Only a portion of the TOPS-20 monitor 
memory at one time.) If a user wishes 'to run a process 
ently in memory, process space must be provided. This 
moving some other process out of memory. The user's 
that is transferred out of memory is placed on disk in 
a. The system sets aside a portion of the disk 

the public structure specifically for this purpose. 



On some timesharing systems, a program must be entirely in main memory 
to execute. Swapping then consists of moving entire iprograms between 
disk and memory. Under TOPS-20, only portions of a program (those 
containing the instructions and data currently being referenced) need 
be in memory. Other portions of the program are brought into memory 
from disk as they are needed. In this case, swapping consists of 
moving portions of a program or data between disk and memory. The 
monitor decides which portions of which programs to swap, and when. 

The size of a program is measured in a unit called ; a page. When 
swapping occurs, some of these pages are copied between memory and 
disk. Figure 4-5 illustrates the concept of swapping. 



CORE MEMORY 


MONITOR 


USER 1 


USER 2 


USER 3 


USER 4 


USER 5 


• 
• 
• 



PAGES OUT 



PAGES IN 




DISK 



Figure 4-5: Swapping Concept 



4.7.2 When to Increase Swapping Space 

For the most part, the size of your swapping space depends on the 
cumulative size of processes you estimate will be on tlhe system at any 
one time. Table 4-5 contains guidelines for estimating the amount of 
swapping space required for an approximate number of user jobs based 
on typical requirements. This amount is given in response to the 
question, "HOW MANY PAGES FOR SWAPPING?" in the software installation 
procedures. 
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The actual disk space used for swapping depends on the number of pages 
you give. The system rounds the number of pages given upward to an 
integral number of cylinders. The swapping space is divided equally 
among the disk packs in the public structure. 

You can allow for swapping space on structures other than the public 
structure. However, this is necessary only if you plan to mount the 
structure as the public structure in the future. Allocating swapping 
space avoids re-creating the structure should you decide to mount it 
as the public structure. 



All the monitors are designed to default to an appropriate number 
pages for swapping. In most cases, you can take this default. 



of 



The guidelines in Table 4-5 apply to systems whose users perform many 
editing jobs and an average or small amount of debugging programs and 
production jobs. If your users perform a great number of debugging 
and production jobs and only a small amount of editing, you should 
double the size of your swapping space. However, if you double the 
size of your swapping space, check the maximum swapping space allowed 
for the monitor you are running. (The TOPS-20 KL Model B Installation 
Guide lists the maximum number of swapping pages you can use with each 
monitor.) You cannot exceed this maximum. If you enter a number that 
is larger than the maximum, the monitor uses the maximum allowed. If 
you must exceed the maximum, you can bring up a larger existing 
monitor, or you can tailor your monitor by following the instructions 
in the BUILD. MEM file. This file is located in the documentation 
files saveset on the TOPS-20 Software Distribution tape. 



Table 4-5: Determining Swapping Space 



I 



Estimated 
Number of Jobs 


Recommended Number of 
Pages for Swapping* 


20 or less 
21 to 30 
31 to 40 

41 to 50 


3000 
4500 
6000 
7500 



* For each additional 10 jobs, increase the number of pages for 
swapping by approximately 1,500. 

If disk space is available, it is better to overestimate the 
swapping space needed. If not enough swapping space has been 
reserved, system service may be disrupted. 
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4.8 DETERMINING THE AVAILABLE DISK SPACE 

4.8.1 Determining Disk Space Before Installation 

To determine the available disk space that you will have to divide 
among your users before installing the system, first calculate the 
swapping space required by your system (Section 4.7.2). Second, 
insert the number you calculated for swapping space into the formula 
shown in Table 4-6, and perform the appropriate steps. 

Table 4-6 outlines how to calculate the available disk space on the 
public structure. If you are calculating the available disk space on 
other structures, follow this same procedure but eliminate reserving 
space for any directories or areas that are not on that structure. If 
any possibility exists that a structure may be useq as the public 
structure, reserve the swapping space. 

NOTE 

Remember that as your system expands, the number of 
pages in the <SYSTEM> and <SUBSYS> directories 
increases. Also, the number of pages reserved for 
directory <SPOOL> should be increased if:: (1) you 
maintain large operator log files (2) users copy large 
numbers of files or large files to LPT:. A large 
backlog of user file retrieval requests can also use 
up much of the <SPOOL> area. 
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Table 4-6 j Calculating Available Disk Space 



Total Disk Space: 








Number of RP04 disk drives * 


38000 pages 
per drive 


= 




TOTAL DISK SPACE 


OR- 








Number of RP06 disk drives * 


76000 pages 
per drive 


= 




TOTAL DISK SPACE 


OR- 








Number of RP07 disk drives * 


216376 pages 
per drive 


= 




TOTAL DISK SPACE 


OR- 








Number of RP20 disk drives * 


201420 pages 
per spindle 


= 




TOTAL DISK SPACE 


OR- 








Number of RA60 disk drives * 


90516 pages 
per drive 


= 




TOTAL DISK SPACE 


OR- 








Number of RA81 disk drives * 


200928 pages 
per drive 


= 




TOTAL DISK SPACE 


Reserved Disk Space: 








Front-end file system 


= 


950 




Swapping Space 
(Enter number of pages 
selected and allocated 
for swapping) 








<SYSTEM> 
<SUBSYS> 
<NEW-SYSTEM> 

< NEW-SUBS YS> 
<OPERATOR> 
<UETP.*> 
<ROOT-DIRECTORY> 

< SPOOL (you should reserve) 


> = 


1876 

1780 

2 

2 

500 

1701 
9 

1000 




TOTAL RESERVED SPACE 


SUBTRACT TOTAL RESERVED SPACE 
FROM TOTAL DISK SPACE 






AVAILABLE DISK SPACE 



4.8.2 Determining Disk Space After Installation 

Shortly after you have installed the system, you can log in as 
OPERATOR and give the command INFORMATION (ABOUT) DISK-USAGE. One 
line of output tells you the actual number of system pages that are 
available on the public structure. You can divide this disk storage 
among your users. (Refer to Chapter 5, Creating Directories.) 
However, be careful about over-allocating disk space on the public 
structure. If the space allowed to user directories exceeds the space 
free on the public structure after installation, then users can fill 
up the entire public structure. But if TOPS-20 cannot free up 
adequate space by expunging the public structure, then system service 
may be disrupted. Even if space can be freed to allow the system to 
keep running, some user programs may be disrupted. 
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A prospective user who requires access to the system must be assigned 
a user name (normally the user's surname), a password, an account, and 
disk storage quotas, and must have a directory created for him or her 
on the public structure. Optionally, you can assign certain 
capabilities and/or make the user or the user's directory a member of 
one or more groups. (Refer to Section 5.8 for a description of how to 
establish group relationships among users and Section 5.9 for a 
description of the capabilities you can assign to users.) You can also 
create additional directories for users on mountable structures. 

This chapter describes three methods you can use to create and 
maintain directories. Using one method, the operator creates and 
maintains all the directories on the system. A second method allows 
you to delegate the responsibility for creating and maintaining 
directories to project administrators. The third method combines the 
first two methods, thus providing additional flexibility. Sections 
5.1 through 5.3 explain these methods and the determining factors for 
choosing one of them. These sections also include some of the 
decisions necessary to assign user names and capabilities, and how to 
allocate disk storage according to the method you use to create and 
maintain directories. (Refer to Chapter 4 to determine the amount of 
disk space available to divide among the directories you create.) 

Chapter 6 describes how to set up an accounting scheme and how to 

assign and validate accounts. You should read Chapter 6 if you want 

to allow users to log into the system and charge their computer usage 

to valid accounts immediately after you have created their 
directories. 

Refer to Chapter 12, The Common File System, for considerations in 
creating directories in a CFS-20 environment. 



5.1 HAVING THE OPERATOR CREATE AND MAINTAIN ALL DIRECTORIES (CENTRAL 
CONTROL) 

In this type of installation, the operator creates a directory on the 
public structure for each new user, and specifies the appropriate 
parameters. The name of the directory is the same as the assigned 
user name. Each user informs the operator when a change to his 
directory parameters is required. This type of operation allows you 
as system manager to have central administrative control over all 
directories and parameters. 
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Therefore, central control means that you or the operator create and 
maintain all the directories for all your system users. Central 
control has two types of directory schemes. One scheme allows you to 
create up to approximately 5,000 directories per structure. The other 
scheme allows you to use subdirectories and create up to approximately 
12,000 directories per structure. 

NOTE 

The number of directories allowed per structure is 
approximate, because the disk space needed to create a 
directory or file varies. 



5.2 DELEGATING THE CREATION AND MAINTENANCE OF DIRECTORIES TO PROJECT 
ADMINISTRATORS (PROJECT CONTROL) 

An alternative type of installation involves project administrative 
control . Under this type of control, the operator creates directories 
only for the users who have been designated as project administrators, 
(e.g., the representatives of major departments). The project 
administrators, in turn, create subdirectories for users within their 
departments or projects and control the assignment of those users* 
directory parameters. This type of control allows you to delegate the 
responsibility for creating and maintaining directories for other 
users and still maintain ultimate control over your system and its 
resources. 

Therefore, project control means that most of the directories created 
by you or the operator are project directories (e.g., MATH might be 
the assigned name of a project). The system's resources, such as disk 
space, are divided among these project directories either equally or 
according to the expected size of the project. Subdirectories are 
then created under project directories for users within the project. 
The people who have been appointed project leaders or administrators 
are responsible for creating, assigning parameters to, and maintaining 
the subdirectories within their project. The resources that you 
allocate to the project directory are divided among its subdirectories 
by the project administrators. Under project control, you are allowed 
to create up to approximately 12,000 directories (including 
subdirectories) per structure. 



5.3 COMBINING CENTRAL AND PROJECT CONTROL 

A combination of central and project control can be used if you want 
to keep the majority of the user directories at the management level 
of control and separate only a portion of your system into projects 
and administrative control. 

Therefore, combining central and project control means that the 
operator creates and maintains directories for most of the system 
users and creates project directories for special projects. The 
project administrators create directories under the project 
directories and are responsible for maintaining them. Combining the 
two types of control still allows up to approximately 12,000 
directories per structure. 
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5.4 CENTRAL AND PROJECT CONTROL DESCRIPTIONS 

Sections 5.4.1 through 5.4.4 describe the two types of central 
control, project control, and the combination of central and project 
control. Each description includes: 

The determining factors for choosing a particular control 

The format, including a diagram, of each type of control 

The procedure for assigning user names 

The procedure for creating user directories 

The procedure for creating files-only directories 

The restrictions, if any, that apply to using a particular 
control 

Also, any additional considerations that apply to headings within each 
description are included. 

Read each description thoroughly. The first central control 
description contains very general information and suggestions that 
apply to all the directory schemes. 



5.4.1 Central Control 
DETERMINING FACTORS ; 

• Your business installation is relatively uncomplicated; 
therefore,, there is no need to separate projects and assign 
the creation and control of directories to various 
administrators. All the directories on the system are 
created and maintained by you or the system operator. 

• You are sure that the number of directories you need is less 
than approximately 5,000. 

FORMAT: 

<ROOT-DIRECTORY> can point to approximately 5,000 directories per 
structure. 

All directories under <R00T-DIRECTORY> are on one level. 
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DIAGRAM: 



CENTRAL CONTROL (5,000 DIRECTORIES) 




<PORADA> 


<FORTRAN-LIB> 



<MCELMOYLE> 



< HOLLAND > 



<T-SOU:RCES> 



UP TO APPROXIMATELY 5,000 DIRECTORIES PER STRUCTURE 



ASSIGNING USER NAMES; 

The user name that you assign should include the user's last name. 
This convention is true for any type of directory scheme that you use. 
The system uses this name when recording the authors of files, sending 
mail to users, and displaying system status. If you follow this 
convention, you can easily identify who is using the system when you 
give a SYSTAT command. If just using last names wi;ll not result in 
duplications, you can simply use the last names. Otherwise, you might 
want to use the first and middle initials followed by the last name. 
(If a user has no middle initial, you can use a dash in its place.) It 
is most convenient for users when user names begin with unique 
characters, allowing use of "recognition" when typing user or 
directory names. Use of leading initials often yields this result. 



CREATING USER DIRECTORIES: 

All directories are created using the "ECREATE command. (Only users 
who have WHEEL or OPERATOR capability enabled can use this command.) 
In the next example, the operator is connected to the jpublic structure 
PUBLIC: and uses the ~ECREATE command to create a nev^ directory named 
<BECKER> for the user who has been assigned the usejr name BECKER. 
Also, the operator assigns the password MARTIN. 

@ENABLE (CAPABILITIES)<RET> 

$"ECREATE (NAME) PUBLIC : <BECKERXRET> 

[NEW] 

$$PASSWORD MARTIN<RET> 

$$<RET> 

$DISABLE (CAPABILITIES)<RET> 

§ 

This directory is called the user's logged- in directory and is always 
on the public structure. Whenever the user logs into the system, he 
is connected to this directory. He can remain in this directory or 
connect to and use files in another directory. 

Refer to the TOPS-20 Operator Command Language Reference Manual for a 
complete description of the ECREATE command that the operator uses to 
create new directories, and the ULIST program that prints information 
about all the directories on the system. 
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After creating a new directory (either files-only or user) , remember 
to update the tape containing the monitor, TOPS-20 Command Processor, 
DLUSER, DLUSER data, DUMPER, <SYSTEM>, and <SUBSYS>. (Refer to 
Chapter 7, System Backup Procedures.) 

CONSIDERATIONS: 



If two users have mistakenly been assigned the same user name and you 
try to create the second directory with this duplication, the system 
prints [OLD] instead of [NEW]. Give the ABORT subcommand, assign the 
user a slightly different user name, and reissue the "ECREATE command 
with the new directory name. A common practice is to precede such 
names with the user's first initial. This allows recognition on the 
user or directory name without typing the entire name and the 
distinguishing character. For instance, if you have the two users 
Stephanie Sheldon and Andrew Sheldon, you should assign them the user 
names S-SHELDON and A-SHELDON or SSHELDON and ASHELDON rather than use 
the names SHELDON-S and SHELDON-A. 

CREATING FILES-ONLY DIRECTORIES: 



If a user wants to have a library area in addition to his logged-in 
directory, you can create a files-only directory on the public 
structure or on another structure. The user can gain owner privileges 
to this directory by giving the CONNECT command and the password 
associated with the directory. If the directory is located on a 
regulated mountable structure, the user must also give the MOUNT 
command to use the structure before he gives the CONNECT command. The 
user cannot give the ACCESS command for or log into a files-only 
directory. 

For example, if you have a user named BECKER who processes payroll on 
a regular basis, he may want to develop the payroll programs in his 
directory and keep the payroll data in a more restricted directory. 
To accomplish this, you can create on the public structure the 
logged-in directory <BECKER> and the files-only directory <PAYROLL>. 
The directory <PAYROLL> can be on some other structure, (e.g., 
ADMIN : <PAYROLL>) . BECKER now has normal protection on his directory, 
more restrictive protection on the directory <PAYROLL> and can still 
CONNECT to <PAYROLL> by giving its password. BECKER cannot, however, 
give the ACCESS command for or log into <PAYROLL>. 

The next example shows how to create the directory <PAYROLL> on the 
public structure MAIN:. 

@ENABLE (CAPABILITIES)<RET> 

$"ECREATE (NAME) MAIN: <PAYROLLXRET> 

[NEW] 

$$PASSWORD MONIES<RET> 

$$FILES (ONLY)<RET> 

$$PROTECTION (OF DIRECTORY) 774000<RET> 

$$DEFAULT (FILE) PROTECTION 770200<RET> 

$$<RET> 

$DISABLE (CAPABILITIES)<RET> 

e 

Now if user BECKER logs in and wants to use the files in <PAYROLL>, he 
can give the following CONNECT command: 

@CONNECT (TO DIRECTORY) <PAYROLLXRET> 
Password: monies<RET> 
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The TOPS-20 Operator Command Language Reference Manual describes all 
the parameters you can give to directories and describes how to create 
directories on mountable structures. 

CONSIDERATIONS: 

When you create additional directories on mountabje structures, 
consider if files-only directories are suitable. Some users will not 
want to give the CONNECT command to a directory each time they require 
owner access to the files in that directory. Also, files-only 
directories are members of groups only as directory groiap members and 
not user group members. Therefore, if you create ALL the directories 
on a structure as files-only, you cannot establish any valid user 
group relationships among those directories. (Refer to Section 5.8 
for a description of setting up groups.) 

Conversely, if you create user directories, users can give the ACCESS 
command to their additional directory and gain owner and group 
privileges without connecting to the directory, and they can use other 
directories on the structure as group members. Also, if the name of 
the directory you create is the same as the user's logged-in 
directory, and the structure is mounted as DOMESTIC, thje user does not 
have to specify a password when giving the CONNECT or ACCESS command 
to the directory. (Refer to Section 4.5.7.) This is valuable when the 
user is submitting a batch job. No password is required on the batch 
input; therefore, security is preserved. In addition to creating user 
directories on the structure, you can create files-only directories to 
be used as library areas. 

It is also possible to create only one user directory on a structure 
and to create all other directories as files-only. la this case, all 
users required to use a files-only directory on the structure could 
give the ACCESS command to the user directory (gaining owner and group 
privileges) , and use the files in a files-only directory according to 
the group protection codes set. This would be usefujl if you have a 
private structure that contains several library areas that are common 
to the owners of the private disk pack(s). Each owner could give the 
ACCESS command for the one user directory and gain group privileges to 
all the library directories. Therefore, these users would need only 
one password to gain access to all the information on tqhe pack. 

Note that defined groups may provide better security controls than 
passwords. If the password for the ADMIN: <PAYROLL> directory is 
MONIES, it might be guessed, or user BECKER may write it down or tell 
it to some other user. On the other hand, group membership can be 
centrally controlled, and the access can be withdrawn, if necessary. 
Also, the directory structure provides a record of group memberships, 
which can be displayed with the ULIST program. Wise uqe of directory 
protections can allow user members of a group to connect to a 
files-only directory without giving a password. 

Refer to the TOPS-20 User's Guide or the TOPS-20 Comnjands Reference 
Manual for a complete description of the CONNECT and AQCESS commands. 

RESTRICTIONS: 

The number of directories you create per structure cannot exceed 
approximately 5,000. This number is an approximation because the disk 
space that it takes to create a directory or file varies. 
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5.4.2 Central Control Using Subdirectories 

DETERMINING FACTORS ; 

• As stated in the previous directory scheme, your installation 
does not warrant segregation of projects and control. 
However, this directory scheme allows more directories per 
structure than the previous central control scheme. You or 
the operator can create up to approximately 12,000 
directories per structure and assign and maintain all the 
directory parameters. 

• You can easily expand into a form of project control by 
adding project directories, and still maintain control at the 
management level over the majority of the user directories. 
(Refer to Section 5.4.4, Combined Central and Project 
Control.) 

FORMAT: 

<ROOT-DIRECTORY> points to 26 directories. The name of each directory 
is a letter of the alphabet, <A>, <B>, <C>, ..., <z>. The directories 
point to all user and files-only directories. The single-letter 
directories are on one level below <ROOT-DIRECTORY>. The user and 
files-only directories are on a second level below <ROOT-DIRECTORY> 
and are pointed to by the alphabetic directories. 

The diagram below illustrates this flow. Also, although it is not 
shown in the diagram, the directories pointed to by the single letter 
directories, (e.g., <A.JONES>) , can be allowed to create directories 
under them. Perhaps user A. JONES wants to create one or two 
subdirectories to store special files, such as memos. The user is 
responsible for maintaining the directory he created and is allowed to 
use only the disk quota you originally allocated to his logged-in 
directory. Refer to Section 5.4.3, Project Control, if you would like 
to allow some users to create directories of their own. 



DIAGRAM: 



CENTRAL CONTROL USING SUBDIRECTORIES 



< ROOT-DIRECTORY > 





< A.SMITH > 



< A.JONES > 



C3. PARKER > 



<C. BAKER > 




<D.LAWES> 





<Z> 














<Z.FORLIB> 




<Z. TESTS > 



UP TO APPROXIMATELY 5.000 DIRECTORIES PER SINGLE LETTER DIRECTORY 
UP TO APPROXIMATELY 12,000 DIRECTORIES PER STRUCTURE 



MR-S-3723-84 
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ASSIGNING USER NAMES ; 

Each user name that you assign should be as close as Possible to the 
user's last name prefixed by a first initial anjd a period. For 
example, Charles Baker would be assigned the user name; C.BAKER. _ Under 
this type of directory scheme, you must follow jthe principle of 
prefixing the name with the first initial and a period. 

CREATING USER DIRECTORIES: 

Have the operator create 26 directories using the "ECREATE command. 
The name of each directory is a letter of the alphabet, that is, <A> 
through <Z>. 

The theory behind creating these alphabetic directories is the same as 
described in Section 5.4.3. That is, you must create directories that 
are allowed to have subdirectories. The directories <A>, <B>, ..., 
<Z> can have approximately 5,000 user and files-only directories under 
them. Therefore, you must include some of the same parameters in 
these directories, as you would in project directories. 

Refer to the TOPS-20 Operator Command Language Reference Manual for a 
complete description of the parameters that are defined when the 
operator uses the "ECREATE command to create directories , and the 
ULIST program that prints information about all directories on the 
system. 

The procedures for creating the alphabetic directories and the user 
and files-only directories under them are described below. In the 
example, COMMON: is the name of the public structure. 

NOTE 

The general considerations described in Section 5.4.1 
for creating directories are also applicable to this 
directory description. 

Even though the alphabetic directories are not associated with users, 

they must be created as log-in directories. However, do not assign 

passwords. This prevents users from gaining access to these 
directories. 

@ENABLE (CAPABILITIES)<RET> 
$"ECREATE (NAME) COMMON: <AXRET> 
[NEW] 
$$ 

Assign each directory a large number for creating subdirectories, for 
example, 400. 

$$MAXIMUM SUBDIRECTORIES (ALLOWED) 400<RET> 

Because many user directories are created under each of these 
alphabetic directories and the page quota (disk space) from these 
alphabetic directories is divided among (or passed oh to) the user 
directories, you must assign the alphabetic directories a very large 
permanent and working page quota. Assigning them a sufficiently large 
page quota prevents any of these alphabetic directories from exceeding 
their page quota, thus requiring, you to make a change to the quota at 
a later time. Therefore, assign each directory at least 500,000 pages 
of permanent and working disk page quota. 

$$PERMANENT (DISK STORAGE PAGE LIMIT) 500000<RET> 
$$WORKING (DISK STORAGE PAGE LIMIT) 500000<RET> 
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Assign a list of SUBDIRECTORY-USER-GROUP numbers to each directory. 
The list should be the same for each directory. The range of numbers 
you use depends on how many groups you plan to establish, (e.g., 5 
groups, 10 groups, 40 groups). The numbers used in the following 
examples are for illustration; you can choose any sequence: 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 200<RET> 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 201<RET> 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 202<RET> 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 203<RET> 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 204<RET> 

Later, when you create a user directory and place that user in a user 
group, you must enter one of the numbers in this list. No other 
numbers will be valid. (Refer to Section 5.4.3, for a more detailed 
description of why you are using this list of numbers, and Section 5.8 
for establishing valid group relationships.) 

In the following example, the operator is connected to the public 
structure COMMON: and creates the first two directories, <A> and <B>: 

@ ENABLE (CAPABILITIES) <RET> 

$~ECREATE (NAME) COMMON: <AXRET> 

[NEW] 

$$ MAXIMUM-SUBDIRECTORIES (ALLOWED) 

$$WORKING 500000<RET> 

$$ PERMANENT 500000<RET> 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 

$$ SUBDIRECTORY-USER-GROUP (ALLOWED) 

$$ <RET> 

$ 

$ "EC RE ATE (NAME) COMMON: <BXRET> 

[NEW] 

$$MAX 400 !You can use abbreviations <ret> 

$$ WORKING 500000<RET> 

$$ PERMANENT 500000<RET> 

$$SUB 200<RET> 

$$SUB 201<RET> 

$$ SUB 202<RET> 

$$SUB 203<RET> 

$$SUB 204<RET> 

$$ <RET> 

$ JContinue creating directories <C> 

$ ! through <Z> in exactly the same manner 



<RET> 



200<RET> 
201<RET> 
202<RET> 
203<RET> 
204<RET> 
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After all 26 directories are created, you can give the DIRECTORY 
command to see all the directory files that have been created under 
<ROOT-DIRECTORY> . 

$DIR COMMON: <ROOT-DIRECTORY> 

COMMON: <ROOT-DIRECTORY> 

A. DIRECTORY. 1 
B. DIRECTORY. 1 
C. DIRECTORY. 1 



Z. DIRECTORY. 1 

Next, after all 26 alphabetic directories have been successfully 
created, the operator again uses the "ECREATE command and creates all 
the user directories. 

In the example below, the operator is connected to the public 

structure COMMON: and creates a directory named <A.JONES> for the 

user who has been assigned the user name A.JONES. This directory is 

A. Jones' log-in directory on the public structure. Each time A. 

Jones logs into the system, he is connected to directory <A.JONES>. 

In this example, the operator also assigns the password 2BY4. The 

operator gives the directory the system default of 2$0 pages for both 

working and permanent disk quota. Because he is using the default, he 

does not have to make any entries for these two parameters. The 250 

pages given to this directory are taken from the superior directory's 

I quota (directory <A>) . (The PRESERVE subcommand can be issued to 

I avoid having the disk space quota subtracted from the superior 

I directory's allocation.) The operator also places user A.JONES in user 

group 202 and places directory <A.JONES> in directory group 202. 

^ENABLE (CAPABILITIES) <RET> 
$~ECREATE (NAME) COMMON: <A.JONESXRET> 
[NEW] 

$$PASSWORD 2BY4<RET> 
I $$USER-OF-GROUP (NUMBER) 202<RET> 
$$DIRECTORY-GROUP (NUMBER) 202<RET> 
$$<RET> 

$DISABLE (CAPABILITIES) <RET> 
§ 

After creating any new directories (either files-only or user) , you 
should update the backup tape that contains the monitor, TOPS-20 
Command Processor, DLUSER, DLUSER data, DUMPER, <SYSTEM>, and 
<SUBSYS>. (Refer to Chapter 7, System Backup Procedures.) 
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CONSIDERATIONS: 

If users have duplicate first initials and last names, you can use 

middle initials. For example, if two users have the name C.BAKER, you 

can assign either one of them a user name in the form CL. BAKER or 

C.LBAKER. If you use the form CL. BAKER you must create a directory 

<CL> in addition to directory <C>. If you do not create this 

additional directory with the user's first and middle initial, you 

will receive error messages and will not be able to create the 

directory <CL.BAKER>. If, instead, you assign user Baker the user 

name C.LBAKER (the preferred method), you can create the directory 

<C.LBAKER> as described above using the standard procedure. You do 

I not need to create the additional directory <CL>. Alternatively, you 

I could create two levels of "initial" directories, and assign users to 

I third-level directories based on their first and middle initials 

I followed by their last names, for example, C.L.BAKER. 

If a user requires special capabilities to perform privileged 
functions, the operator can include the parameter for the capability 
in the user's directory accordingly. (Refer to Section 5.9 for a 
description of the capabilities you can assign to certain users who 
require them.) 

CREATING FILES -ONLY DIRECTORIES: 



If a user wants a library area in addition to the logged-in directory, 
you can create a files-only directory. 

Files-only directories can also be prefixed by a letter and a period. 
Because the first name initials of users do not always encompass every 
letter in the alphabet, you may want to use those infrequently used 
letters as the prefix to the files-only directories, e.g., <X.FORLIB> 
or <Z.TESTS>. Alternatively, you can place the files-only directories 
under a special prefix, such as LIB., or place them directly under the 
root directory. The example below shows how to create the directory 
<X.FORLIB> on the public structure PUBLIC:. The operator assigns the 
password SQUASH, makes the directory files-only, takes the 250-page 
default for working and permanent disk storage quotas, and places the 
directory in directory group number 202. (User members of groups 202 
can now accesss this directory and the files it contains according to 
group protections,) 

@ENABLE (CAPABILITIES)<RET> 

$"ECREATE (NAME) PUBLIC : <X. FORLIBXRET> 

[NEW] 

$$PASSWORD SQUASH<RET> 

$$FILES-ONLY<RET> 

$$DIRECTORY-GROUP (NUMBER) 202<RET> 

$$<RET> 

$DISABLE (CAPABILITIES)<RET> 

@ 

Follow the procedures in the TOPS-20 Operator's Guide for creating 
directories on mountable structures. 
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CONSIDERATIONS; 

The CONSIDERATIONS described in the previous central control 
description (Section 5.4.1) for files-only directories also apply to 
this description. 

If the number of files-only directories you want to create is small, 
you can create them on the same level as the alphabetic directories. 
That is, <X.FORLIB> can be created as <FORLIB>. Your directory scheme 
may look like: 



<ROOT-DI RECTORY > 




< A. JONES > 



<X.FORLIB> 



< ROOT-DI RECTORY > 




<FORLIB> 



< A. JONES > 



RESTRICTIONS: 

The number of directories you can create per structure cannot exceed 
approximately 12,000. 

The number of subdirectories under a single-letter directory, for 
example, <A>, cannot exceed approximately 5,000. 
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If you reach the maximum number of directories allowed per structure, 
the system prints the message: 

MAXIMUM DIRECTORY NUMBER EXCEEDED; INDEX TABLE NEEDS EXPANDING 

If you reach the maximum number of subdirectories that a single letter 
directory can point to, the system prints the message: 

SUPERIOR DIRECTORY FULL 

You can define up to only 40 user groups with the "ECREATE command, 
because all the user groups must be specified as subdirectory user 
groups in the superior single-letter directory. This is not as great 
a problem when all the user directories are directly under the 
ROOT-DIRECTORY. 

If you make a superior directory FILES-ONLY, be sure to make all its 
subdirectories FILES-ONLY. Otherwise, you will be unable to recreate 
the subdirectories (refer to Chapter 9) if the structure is damaged, 
until all the superior directories are made not FILES-ONLY. 



5.4.3 Project Control 



DETERMINING FACTORS: 



The complexity and perhaps geography of your organization 
warrants separating small or large groups of users into 
projects. The responsibility for creating and maintaining 
the directories within a project can be given to an 
administrator. This is especially helpful if a large number 
of users have directories on the system. This method frees 
the operator from spending an excessive amount of time 
creating directories and changing directory parameters. 



Even though you delegate the task of crea 
groups of directories to project admini 
maintain ultimate control of the overal 
resources. This means that you still det 
the disk space that each project uses, 
distributes the disk space you allocate to 
the project. Also, administrators can cr 
directories for their projects without 
OPERATOR capabilities by using the TOPS- 
Therefore, you do not weaken the secur 
Unless you give WHEEL or OPERATOR ca 
administrator, he cannot assign those ca 
users. 



ting and managing 

strators, you still 

1 system and its 

ermine and allocate 

The administrator 

directories within 

eate and maintain 

having WHEEL or 

20 BUILD command. 

ity of your system. 

pabilities to an 

pabilities to other 



In addition to allowing administrators to create directories 
for a project, you can allow other users of the system to 
create subdirectories. These users can separate and store 
files in a subdirectory. According to the protection they 
place on their subdirectories, they can share their files 
with other users without losing the security of their 
superior directory. The users are responsible for 
maintaining the directories they create. 



• Up to 12,000 directories (including 
created per structure. 



subdirectories) can be 
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FORMAT: 



<ROOT-DIRECTORY> can point 
structure. 



to approximately 5,000 directories per 



Each directory under <ROOT-DIRECTORY> can point to approximately 5,000 
subdirectories. 

Each subdirectory can also point to approximately 5,000 subdirectories 
directly under it. 

The number of subdirectory levels is determined by a maximum length of 
39 alphanumeric characters, because each subdirectory name contains 
the name or names of any superior directories above it. Using the 
diagram below, the user who owns directory <PHYSICS> under 
<ROOT-DIRECTORY> creates the subdirectory <PHYSICS.LAB-12>. The new 
subdirectory name (LAB-12) has its superior directory's name (PHYSICS) 
as its prefix. The period separates the different levels of the 
directory name and is counted as one of the characters in the 
directory name. 

DIAGRAM: 



PROJECT CONTROL (12,000 DIRECTORIES) 



<ROOT-DIRECTORY> 




<HURLEY> 



<CHEM> 



< PHYSICS > 



<CHEM. 
HESS> 



<CHEM. 
STUDENT > 



<CHEM. 
STUDENT > 



< PHYSICS. 
LAB-12> 



< PHYSICS. 
LAB-12. 
STUDENT > 



< MILLER > 



<COMP.SCI > 



<MILLER. 
ADMIN > 



<MILLER. 
TESTS > 



< PHYSICS. 
STUDENT > 



< PHYSICS. 
STUDENT > 



< PHYSICS. 
LAB-12. 
STUDENT > 



<COMP-SCI. 
STUDENT > 



<COMP-SCI. 
STUDENT > 



< PHYSICS. 
LAB-12. 

STUDENT > 



UP TO APPROXIMATELY 5,000 SUBDIRECTORIES PER DIRECTORY 
UP TO APPROXIMATELY 12,000 DIRECTORIES PER STRUCTURE 



MR-S-3724-84 
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ASSIGNING USER NAMES: 



The names that you assign to users should be as close as possible to 
the user's last name. In addition, the project names that you assign 
and that will be used for project directory names should be closely 
related to the project, e.g., PHYS might be used for Physics and PHYED 
for Physical Education. 

When you give a SYSTAT command, the user surnames and obvious project 
names make it easier to identify who is using the system, and under 
which project. 

CREATING PROJECT AND USER DIRECTORIES: 



The user and project directories that <ROOT-DIRECTORY> points to 
(first-level directories) are created by you or the operator using the 
"ECREATE command. 

The procedures you should use and the parameters that you must include 
in these directories are described below. 

Create all project directories as log-in (user) directories. You 
would not create a project directory as files-only, because files-only 
directories cannot have log-in directories created under them. 
However, log-in project (or user) directories can have both log-in and 
files-only subdirectories. 

Assign a disk storage quota to each project directory. This quota 
must be large enough to accommodate both the files that are contained 
in the directory and the directories that are created under it. Each 
time a directory is .created under a project directory, that 
directory's disk quota is taken from the project directory's disk 
quota. The total disk quota for directories created under a project 
directory cannot exceed the quota originally given to the project 
directory. 

In the example below, the operator begins to create the project 
directory <CHEM>, He creates the directory as a log-in directory on 
the public structure ORANGE: and assigns the password H20. This 
procedure allows an administrator to log into the directory, giving 
its password, and create the required subdirectories. He may also 
want to store his files in this directory. The operator gives the 
directory a 10,000-page working and a 10,000-page permanent disk 
storage quota. 

@ENABLE (CAPABILITIES) <RET> 

$~ECREATE (NAME) ORANGE: <CHEMXRET> 

[NEW] 

$$PASSWORD H20<RET> 

$$WORKING 10000<RET> 

$$PERMANENT 10000<RET> 

$$ 
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Next, the operator enters the parameter that allows the owner of the 
project directory to create subdirectories. This parameter, called 
MAXIMUM-SUBDIRECTORIES (ALLOWED) , specifies how many directories can 
be created under the directory. Unless you enter this parameter (the 
default is 0) , the owner of the directory cannot create 
subdirectories. For example, all users of the system can type the 
BUILD command to the TOPS-20 Command Processor, but only those users 
who have the MAXIMUM-SUBDIRECTORIES (ALLOWED) parameter in their 
directory with a number greater than zero can actually use the BUILD 
command to create subdirectories. 

The following entry in the sample project directory <CHEM> allows the 
administrator to create 100 subdirectories. 

$$MAXIMUM-SUBDIRECTORIES (ALLOWED) 100<RET> 

The administrator who is responsible for this sample project might 
create 60 directories under the project directory and give each 
subdirectory approximately 50 pages of working and permanent disk 
quota. He keeps enough pages in the project directory to allow that 
directory's files to grow and to create additional subdirectories. 
(Refer to the TOPS-20 Commands Reference Manual for the description of 
the BUILD command, including distributing working and permanent 
storage quotas and maximum subdirectory quotas.) 

Also, some of the MAXIMUM-SUBDIRECTORIES (ALLOWED) quota given to the 
project directory can be given to a subdirectory so that directories 
under it can be created. The quota for the project directory is 
decremented by the amount of quota given to the subdirectory. 

For example, directory <CHEM> is given a subdirectory quota of 100. 
The administrator creates the directory <CHEM.STUDENT> under <CHEM> 
and gives the directory a subdirectory quota of 10. The number of 
subdirectories that can now be created under <CHEM> is 89. If the 
administrator creates another subdirectory under <CHEM> called 
<CHEM.STUDENT2> and gives that directory a subdirectory quota of 6, 
the number of subdirectories that can now be created under <CHEM> is 
82. 

If the administrator gives an INFORMATION (ABOUT) DIRECTORY <CHEM> 
command, the output line for maximum subdirectory quota is: 

MAXIMUM NUMBER OF SUBDIRECTORIES ALLOWED 84 

The two directories <CHEM.STUDENT> and <CHEM.STUDENT2> that were 
created under <CHEM> account for the two subdirectories not shown in 
the subtraction. 

Next, the operator enters the parameter that allows the administrator 
for this project to place users in groups. The administrator can use 
the group facility as described in Section 5.8 to set up library 
directories and allow file sharing among members of the project. 
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The SUBDIRECTORY-USER-GROUP parameter accepts a number between 1 and 
262143 as Its argument. You can list a range of numbers that the 
administrator can use to establish groups within the project; however, 
you must enter each number separately. Be careful to assign a range 
of numbers that is unique to that project. For example, project 
directory <CHEM> may be given the range: 



$$SUBDIRECTORY-USER-GROUP 
$$SUBDIRECTORY-USER-GROUP 
$$SUBDIRECTORY-USER-GROUP 
$ $S UBDIRECTORY-US ER-GROUP 
$$SUBDIRECTORY-USER-GROUP 



(ALLOWED) 2600<RET> 

(ALLOWED) 2601<RET> 

(ALLOWED) 2602<RET> 

(ALLOWED) 2603<RET> 

(ALLOWED) 2604<RET> 



Project directory <PHYSICS> may be 
numbers different from project CHEM. 



given the following range of 



$$SUBDIRECTORY-USER-GROUP (ALLOWED) 3001<RET> 

$$SUBDIRECTORY-USER-GROUP (ALLOWED) 3002<RET> 

$$SUBDIRECTORY-USER-GROUP (ALLOWED) 3003<RET> 

$$SUBDIRECTORY-USER-GROUP (ALLOWED) 3004<RET> 

$$SUBDIRECTORY-USER-GROUP (ALLOWED) 3005<RET> 

If you assign the same range of numbers to different projects, you can 
cause a security break among projects. For example, a user in group 
2602 in project CHEM should not be able to access, as a group member, 
the directories and files in project PHYSICS. 

The range of numbers placed in a project (or user) directory's 
parameter list does not imply that the directory or any of its 
subdirectories has access to those groups. It means only that the 
administrator (or owner of the directory) can use those group numbers 
to establish group relationships among that directory and its 
subdirectories. 

The following example shows the completed parameter list for the 
sample project directory <CHEM>: 

@ENABLE (CAPABILITIES) <RET> 

$ "ECREATE (NAME) ORANGE: <CHEMXRET> 

[NEW] 

$$PASSWORD H20<RET> 

$$WORKING 10000<RET> 

$$PERMANENT 10000<RET> 

$$MAXIMUM SUBDIRECTORIES (ALLOWED) 100<RET> 

$$SUBDIRECTORY-USER-GROUP (ALLOWED) 2600<RET> 

$$SUBDIRECTORY-USER-GROUP 

$$SUBDIRECTORY-USER-GROUP 

$$SUBDIRECTORY-US ER-GROUP 

$$SUBDIRECTORY-USER-GROUP 

$$<RET> 

$ DISABLE (CAPABILITIES) <RET> 

§ 



(ALLOWED) 2601<RET> 

(ALLOWED) 2602<RET> 

(ALLOWED) 2603<RET> 

(ALLOWED) 2604<RET> 



Refer to the TOPS--20 Operator's Guide for a complete description of 
the "ECREATE command that the operator uses to create new directories, 
and the ULIST program that prints information about all the 
directories on the system. 

After creating a new directory (either user or files-only) , remember 
to update the backup tape that contains the monitor, TOPS-20 Command 
Processor, DLUSER, DLUSER data, DUMPER, <SYSTEM>, and <SUBSYS>. 
(Refer to Chapter 7, System Backup Procedures.) 
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CONSIDERATIONS; 

If two projects or users have mistakenly been assigned the same name, 
and you try to create the second directory with this duplication, the 
system prints [OLD] instead of [NEW], Give the ABORT subcommand, 
assign the user or project a slightly different name, and reissue the 
"ECREATE command with the new directory name. 

A subdirectory is just like any other directory. It can be logged 
into (if it is not specified as files-only) , it can be a member of 
user and directory groups, and it obeys the usijial protection 
mechanisms. Therefore, there are no implied rights between a 
directory and its subdirectories, or between two subdirectories of the 
same directory. Files have three protection fields! owner, group, 
and world; and each directory has the same three protection fields. 
Refer to Section 5.7 for a description of directory and file 
protections. 

The only additional rights that the owner of a directory has over that 
directory's subdirectory is the power to change its parameters (e.g., 
directory protection, password, or group memberships), or to use the 
KILL subcommand, which deletes the subdirectory. 

If you or another user choose to delete a directory, you must first 
delete any subdirectories under the directory. You cannot delete a 
directory or subdirectory that has existing subdirectories. This 
protection insures that someone (possibly an administrator of a 
project) does not accidentally delete a directory that points to a 
large portion of the database. The operator or administrator must 
connect to the directory immediately above the lowest level 
subdirectory to begin deleting any directories. For example, using 
the diagram in the FORMAT description, if the owner of the directory 
<PHYSICS> wants to delete the directory <PHYSICS.IJ.AB-12>, he must 
first connect to directory <PHYSICS. LAB-12> and delete the three 
<PHYSICS.LAB-12.STUDENT> directories. Then, he connects to directory 
<PHYSICS> and gives the KILL subcommand to delete directory 
<PHYSICS.LAB-12>. Note that the operator is the only person who can 
delete the directory <PHYSICS>. 

If you or the administrator choose to grant special capabilities to a 
user, you can include the parameter for the capability in the user's 
directory. (Refer to Section 5.9 for a description of the 
capabilities you can assign to certain users.) You should instruct the 
administrator to inform you when special capabilities 4 re given to a 
system user. You are protected against users randomly giving other 
users special capabilities, because the operator or th6 administrator 
who assigns special capabilities to a user must have (as a user) those 
same capabilities. A person with WHEEL or OPERATOR capabilities can 
assign any capability to another user. Also, the user or operator who 
is assigning the capabilities must have those capabilities enabled at 
the time the privileged parameter is entered into the user's 
directory. 

Once a SUBDIRECTORY-USER-GROUP number has been allocated to a project 
directory, be careful about removing it. If it is ^n use in any of 
the subdirectories, either as a USER-OF-GROUP nurjiber or as a 
SUBDIRECTORY-USER-GROUP number, you will be unable j to recreate the 
subdirectories (refer to Chapter 9) if the structure i$ damaged, until 
you manually restore the SUBDIRECTORY-USER-GROUP number into all the 
superiors. 
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CREATING FILES-ONL Y DIRECTORIES; 

Administrators or users can have library areas in addition to their 
logged-in directories. They can use the BUILD command and create 
files-only directories under their logged-in directories, provided you 
have given them the capability to do so by adding the MAXIMUM 
SUBDIRECTORIES (ALLOWED) parameter to the directory that will contain 
the subdirectories. 

CONSIDERATIONS: 



Refer to the CONSIDERATIONS under the first description of Central 
Control, Section 5.4.1. These considerations also apply to Project 
Administrative Control. 

RESTRICTIONS? 



• You cannot exceed approximately 12,000 directories per 
structure. 

• The number of directories that a superior directory points to 
cannot exceed approximately 5,000. 

If you reach the maximum number of directories that you can create on 
a structure, the system prints the message: 

MAXIMUM DIRECTORY NUMBER EXCEEDED; INDEX TABLE NEEDS EXPANDING 

If either you or an administrator reach the maximum number of 
directories that can be created under a superior directory, the system 
prints the message: 

SUPERIOR DIRECTORY FULL 

• Files-only directories cannot have log-in subdirectories. If 
you want to allow a user to create user (log-in) 
subdirectories under his directory, you must make his 
directory a log-in directory. 



5.4.4 Combined Central and Project Control 

DETERMINING FACTORS: 

• Only a portion of your organization warrants being separated 
into projects. The directories for the majority of the user 
community are created and maintained at the central 
management level.' But, where project administration is 
appropriate, the task of creating and managing directories 
within a project is given to administrators. 

• For example, if your company has groups of users with 
terminals in several distant locations, you may want to have 
the administrator at the remote location create and maintain 
all the directories for that site. You can create a project 
directory for the remote location, perhaps using the name of 
the site as the project directory name (for example, 
<CHICAGO> or <CHIC>, <SEATTLE>, ...). The remaining user 
directories at the central location are created by the system 
operator. 
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FORMAT; 

<ROOT-DIRECTORY> points to all the project directories and 26 
alphabetically named directories, <A> through <Z>. The project 
directories point to the user and files-only directories that an 
administrator creates for a given project. The directories <A> 
through <Z> point to user and files-only directories created and 
maintained by the operator. These directories can also be allowed to 
have subdirectories. 

DIAGRAM: 



COMBINED CENTRAL AND PROJECT CONTROL (12.000 DIRECTORIES) 



< ROOT-DIRECTORY > 



< CHICAGO > 



< BOSTON > 




< SEATTLE > 



< A.JONES > 



< A.SMITH > 



< BOSTON. 
ESTEY > 



< BOSTON. 
HALL> 



<Z.FORLIB> 



< A. SMITH. 
MEMOS > 



< SEATTLE. 
SALES > 



< SEATTLE. 
SMITH > 



< SEATTLE. 
BOSACK > 



< CHICAGO. 
HESS> 



< CHICAGO. 
OVERHEAD > 



< CHICAGO. 
INV> 



< SEATTLE. 
SALES. 
OVERHEAD > 



< SEATTLE 
SALES. 
PROJECTION > 



UP TO APPROXIMATELY 5,000 SUBDIRECTORIES PER DIRECTORY 
UP TO APPROXIMATELY 12,000 DIRECTORIES PER STRUCTURE 
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ASSIGNING USER NAMES; 



If you create any user directories that are pointed to by 
<ROOT-DIRECTORY>, assign project names and user names in the same 
manner as described under Project Control, Section 5.4.3. Again, 
assign the 26 directories that will point to the majority of the user 
directories, the names <A>, <B>, <C> .... <Z>. The user names that 
will be the directory names under the alphabetic directories should, 
as previously stated, be the user's surname prefixed by a first 
initial and a period. (Refer to Section 5.4.2, Central Control Using 
Subd irectories.) 
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CREATING USER AND FILES-ONLY DIRECTORIES: 



Create the user, files-only, and <A> through <Z> directories by 
following the instructions in Section 5.4.2. 

Create the project directories according to the instructions in 
Section 5. 4.3, and distribute the description of the BUILD command 
( TOPS-20 C ommands Reference Manual ) to the administrators who are 
responsible for creating the user directories within their project. 

CONSIDERATIONS: 



All the considerations that apply to both Central and Project Control 
also apply to combining the two types of control. 

You may want to allow users whose directories are created by the 
operator to create several directories under their logged-in 
directories. The diagram under FORMAT illustrates this facility. 
User A.SMITH has created the subdirectory <A. SMITH. MEMOS> to store 
files that he wants to keep separate from his programming files. This 
user uses the BUILD command to create the number of subdirectories 
that he is allowed to create and divides the quota for his logged-in 
directory among the directories he creates. 

In general, users can store files in these directories or, if they set 
the appropriate protection, can share the files in these directories 
with other users. 

RESTRICTIONS: 



Combined Central and Project Control allows up to approximately 12,000 
directories per structure. 

The number of directories that a superior directory can point to 
cannot exceed approximately 5,000. 

If you reach the maximum number of directories per structure, the 
system prints the message: 

MAXIMUM DIRECTORY NUMBER EXCEEDED; INDEX TABLE NEEDS EXPANDING 

If you reach the maximum number of directories that a superior 
directory can point to, the system prints the message: 

SUPERIOR DIRECTORY FULL 



5.5 ALLOCATING DISK STORAGE QUOTAS 

In Chapter 4 you determined the amount of disk space that is available 
on the public structure after installation. Once you know the 
available disk space, you can decide how to allocate it among the 
directories you create. Each directory is given a number of pages for 
both working-storage and permanent-storage allocations. Working 
storage refers to the disk space that a user can have during the time 
he is logged-in. Permanent storage refers to the total disk space 
that a user can have to store files after he has logged-out. 
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The number of pages that you should assign to directories depends on 
whether you (or the operator) are creating all the directories on the 
system (central control) or you are delegating the task of creati"" 
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certain users. In the case in which the operator creates project 
directories, you should allocate a disk quota large enough to 
accommodate the expected size of each project. Remember that project 
directories must distribute their disk space to the directories 
created under them. 

Several important points about working and permanent allocations are 
discussed below. 

Assign a large (2000-3000 page) working-storage allocation to users 
who perform considerable sorting because the temporary files required 
for this operation can occupy substantial disk space. 

As the number of users on the system increases and your disk space on 

the public structure becomes low, you can decrease the working-storage 

and permanent allocations on the public structure to add new log-in 

directories. If you have additional disk drives not used by the 

public structure, you can accommodate the directories with many or 

large files by creating other structures and directories. Users will 

log into their directories on the public structure, request the 

operator to mount the proper structure using the MOUNT command, and 

access their additional directories with the ACCESS and/or CONNECT 

I command. Note that in setting up the system, it is easier to accustom 

I users from the start to use other structures than to ; reorganize the 

1 structures and retrain users after space has run out on the public 

I structure. 



5.6 ENFORCING DISK STORAGE QUOTAS 

Working-storage allocations are strictly enforced. Users cannot 
exceed their working-storage allocations unless they enable WHEEL or 
OPERATOR capabilities. (Refer to Section 5.9 for a description of the 
special capabilities that can be given to users who require them.) If 
users request additional space, you can increase their allocations as 
required. 

If a user exceeds his working-storage allocation and attempts to 
create or change a file, the system prints the following error 
message: 

7QU0TA EXCEEDED 

The user must decrease his disk usage to less than the working-storage 
allocation for the directory (in which the file is being changed or 
created) before he can create or change any more files. 

The system informs a user if he is over this permanent storage 
allocation when he logs off the system or connects to a different 
directory. The system prints the following message after the CONNECT 
or LOGOUT commands: 

<directory>OVER PERMANENT STORAGE ALLOCATION BY nn PAGES 
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This message reminds users that although they may not be over their 
working-storage allocation, they have exceeded their expected total 
disk usage. Users should delete any files that are unnecessary for 
their job. Also, because permanent quotas are not enforced, it is 
wise to instruct the operator or administrator to police each 
directory's disk usage. The operator should run the CHKPNT program 
daily to keep a record of each directory's disk usage. The TOPS-20 
Operator's Guide contains the description of running the CHKPNT 
program. If you are using the file migration facility (refer to 
Chapter 8) , you may want to run the REAPER program with the TRIM 
command to force users to stay below their permanent quotas. 

Every time the available disk space on the public structure is less 
than 500 pages, the system prints the following warning message: 

[CAUTION-DISK SPACE LOW ON structure name] [DELETED FILES WILL BE 
EXPUNGED IN 30 SECONDS] 

After 30 seconds, the system prints the following message and starts 
expunging any deleted files in all directories on the structure 
mentioned in the warning message: 

[EXPUNGING DELETED FILES] 

The system prints this message when the expunging is complete: 

[SYSTEM EXPUNGE COMPLETED] 

If anyone tries to create or change a file when there is no more disk 
space available, the system prints an error message similar to the one 
below: 

?FILE OR SWAPPING SPACE EXCEEDED 

Again, the operator or administrator should check to see how many 
users are over permanent allocations. Also, if you are using the file 
migration facility, you may want to migrate files on the system more 
frequently if you are constantly running low on systemwide disk space. 
(Refer to Chapter 8 for a description of file migration.) 



5.7 PROTECTING DIRECTORIES AND FILES 

Every directory and file has a protection number associated with it. 
The system uses a default protection number for each directory and 
file when the directory or file is created. 

Whenever a user accesses a file, the system first checks the directory 
protection. If that protection allows the user the appropriate access 
to the directory, the system then checks the protection of the 
individual file. 
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5.7.1 Directory and File Protection Digits 

The directory and file protection numbers have three 2-digit fields. 
The first field applies to ' the owner of the directory or file, the 



second field to members of the same group as this directory, 
third field to all other users (or world) . 

Protection Code 



and 



le 
the 



dd 



dd 



dd 



_l 



Owner 



Group 



World 



The default protection for directories and files . is 777700. A 
directory or file protection of 77 in any given field allows full 
access. For example, the default protection allows the owner and 
members of his group full access but all other users no access. 

Protection Code 



77 


77 


00 



Owner Group World 
Table 5-1 contains a list of the directory protection digits. 



Table 5-1: Directory Protection Digits 



Digits 



04 
10 



40 



Privilege 



Permits creating files in the directory. 

Permits connecting to the directory without giving a 
password and changing the accounts and protection 
numbers of the files therein. Thus it gives many of 
the privileges the directory owner has. (Refer to the 
TOPS-20 Monitor Calls manual.) 

Permits, subject to the protection on the individual 
file, listing the names of the fij.es with the 
DIRECTORY command and reading the file, e.g., via the 
TYPE, PRINT, or LIST commands. ^^ 



These protection codes are actually bits in a protection word. To get 
more than one protection, add the digits (octal) corresponding to the 
protection you want. Thus, 44 allows listing the files and creating 
new files. There are unused bits in the protection number; therefore, 
to provide complete access to files, use 77. Useful digit pairs are: 

00 Permits no access. 

40 Permits the files to be listed and read. 

77 Permits full (owner) access. 

A file protection number has the same format as a directory protection 
number, but the meanings of the digits are different. Table 5-2 
contains a list of file protection digits. 
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Table 5-2: File Protection Digits 



Digits 



2 
04 
10 
20 
40 



Privilege 



Permits wildcarding of the file. 
Permits appending to the file. 
Permits executing the file. 
Permits writing and deleting the file, 
Permits reading the file. 



Obtain a protection number by adding the file protection digits of the 
different protections you need. For example, protection number 775200 
allows the owner full privileges; the members of the same group 
reading, executing, and directory listing privileges; and all other 
users no privileges. Useful digit pairs are: 



I 00 



12 



Permits listing the file with the DIRECTORY command only if the 
file is specified explicitly and completely. 



Permits executing and using the DIRECTORY command 
file only. 



to list the 



This protection is useful when, for example, you purchase a 
program and agree in your contract not to allow any of your 
system users to read, write into, or copy the file. Set the 
protection on an execute-only file to 771212. The TOPS-20 Beware 
file provides additional considerations for setting 
execute-only files. 



up 



52 



Permits reading, 
list the file. 



executing, and using the DIRECTORY command to 



77 Permits full access. 

The system checks protection numbers starting with the two rightmost 
digits. Therefore, users do not restrict members of a group by 
assigning the file protection 770052, because the group gets at least 
the execute, read, and directory list access (52) granted to all 
users. 



Also, because 
file protecti 
still secure i 
For example, 
the directory 
777700 and t 
and directory 
protection a 
protection, 77 
access to th 
even though th 
the file to 
if KOHN were a 



the system checks the d 
on, files that have bee 
n a directory with the 
suppose the user KOHN t 
<HESS>. The protectio 
he protection on the fi 

<HESS> are not in 
pplies. First, the 
7700. The last two dig 
e directory. User KOHN 
e corresponding protect 
be read, executed, and 
llowed access to files 



irectory protection before the 

n given a low file protection are 

default directory protection. 

ries to type the file EDIT. MAC in 

n on the directory <HESS> is 

le EDIT. MAC is 777752. User KOHN 

the same group, so the world 

system checks the directory 

its (00) apply and permit no 

is not allowed to type the file, 

ion on the file (52) would allow 

listed with the DIRECTORY command 

in the directory. 
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5.7.2 Changing Directory and File Protection 

Users can change file protection numbers via the SET FILE PROTECTION 
command or the RENAME command. 

Users can change directory protection numbers via the SET DIRECTORY 
PROTECTION or BUILD command. You can, however, prevent users from 
making changes to their directory protection numbers by including the 
DISABLE DIRECTORY-PARAMETER-SETTING command in the system file called 
<SYSTEM>n-CONFIG.CMD on the public structure. If you make this entry 
in n-CONFIG.CMD, only users with WHEEL or OPERATOR capabilities can 
change directory parameters (via the ENABLE and SET DIRECTORY 
PROTECTION commands) . 

NOTE 

Make an entry in n-CONFIG.CMD only if you DO NOT want 
to allow users to change their directory protections; 
otherwise, the system assumes that you want to use the 
system default command of ENABLE 
DIRECTORY-PARAMETER-SETTING. (Refer to the TOPS-20 KL 
Model B Installation Guide for a description of the 
parameters that are placed in the n-CONFIG.CMD file.) 



5.8 ESTABLISHING GROUPS 

You can let users share files by placing users and directories in 
groups. Members of a group can access directories and files in that 
group according to the middle digits of the directory and file 
protection code fields. 



PROTECTION CODE FIELD 



dd 


dd 


dd 



OWNER \ / "WORLD" 



GROUP 



MR-S-544-80 



Each group that 
<DIRECTORIES>. 
included as o 
belonging to 
user can belong 
relationships 
DIRECTORY-GROUP 
BUILD commands. 
Smith in user g 



you establish has two types of members: USERS and 

Each group is identified by a number. This number is 

ne of the directory parameters in each directory 

the group. Any directory (including subdirectories) or 

to as many as 40 groups. You can set up group 

in the * individual directories by using the 

and USER-OF-GROUP subcommands to the "ECREATE and 

The following example shows that you have placed user 

roup 268 and directory groups 268 and 418: 



@ENABLE (CAPABILITIES) <RET> 

$"ECREATE (NAME) MAIN: <SMITHXRET> 

$$ PASSWORD SOAR<RET> 

$$WORKING 500<RET> 

$$PERMANENT 500<RET> 

$$ USER-OF-GROUP 268<RET> 

$$ DIRECTORY -GROUP 268,418<RET> 

$$ 
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The DIRECTORY-GROUP or USER-OF-GROUP parameter that you place in the 
user's directory determines: 1) if this user can access another 
directory's; files as a group member 2) if the files in this user's 
directory can be accessed by another user as a group member, or 3) 
both. The diagrams on the following pages illustrate the difference 
between being a member of a group as a directory and/or as a user. 



When a user accesses a f 
same group, the system 
of the directory. When, 
not the owner, the s 
same group as this direc 
are in the same group; 
now checks the group pro 
accessed. If the group 
user requested, the syst 
the individual file. 



ile in a directory that is a member of the 
first checks to see if this user is the owner 
in this example, it finds that the user is 

ystem then checks to see if the user is in the 

tory. In this case, the user and directory 
that is, the group numbers match. The system 

tection code field of the directory being 
protection allows the type of access that the 

em proceeds to check the group protection on 



If you are setting up groups on different structures, there is no 
correlation between a group number on one structure and the same group 
number on another structure. For example, group 20.2 on MAIN: does 
not necessarily have the same user and directory members as group 202 
on another structure. 




Each directory has two lists of group 
numbers: Directory Group Numbers and 
User Group Numbers. 



Directory Group Numbers 
various groups of 
<DIRECTORY> is a member. 



identify the 
which this 



User Group Numbers are associated with 
users and identify the various groups 
of which each user is a member. 
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The Directory Group Numbers are 
important to users wHio require access 
to this directory. Those users who 
have a matching group number in the 
User Group Number List can access this 
<DIRECTORY> according to its group 
protection code. 



The User Group Numbers are important 
to the owner of this directory. This 
owner can access any directory that 
has a matching group number in its 
Directory Group Number List. Note: 
Because files-only directories are not 
associated with a user, they do not 
contain User Group Numbers. 



MR-S-546-80 



There are three common types of groups: 

1. A file-sharing group, whose users can access a set of library 
directories and each other's logged-in directories. 



2. 



3. 



A library group, whose users can access a set of library 
directories and their own logged-in directories, but not each 
other's logged-in directories. 

A teacher-student group, in which the teacher can access the 
students' directories and the students can access their own 
logged-in directories, but not their classmates' directories 
or the teacher's directory. 



Figures 5-1 through 5-3 illustrate these three common groups and 
association between USER and <DIRECTORY> members of a group. 



the 



In a file-sharing group (Figure 5-1), users share all their files 
according to the group protection field, both in the library 
directories (here it is <MANUALS>) and in their logged-in directories. 
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USER PORADA 



USER HOLLAND 




Figure 5-1: File-Sharing Group 



In Figure 5- 
same group 
<MANUALS> ar 
access their 
code fields, 
according to 
can access d 
protection 
indicate tha 
group. 



1, the two users, PORADA and HOLLAND, are members of the 

(group 2). The directories <PORADA>, <HOLLAND>, and 

e also members of group 2„ Users PORADA and HOLLAND can 

own directory and files according to the owner protection 

PORADA can access directories <HOLLAND> and <MANUALS> 

the group protection code fields, and conversely, HOLLAND 

irectories <PORADA> and <MANUALS> according to their group 

code fields. The other numbers shown in the figure 

t a user or directory can be a member of more than one 



In a library group (Figure 5-2), USER members can access all the 
<DIRECTORY> members but not each other's logged-in directories. The 
library directories are usually files-only directories. This figure 
illustrates a library group that consists of the files-only 
directories: <SUBROUTINES>, <TAPE-TESTS>, <MACROS>, and users! 
ALUSIC, BROPHY and KOHN. This library group illustrates that just 
because you are a member of a group as a user, your logged-in 
directory need not belong to the same group. 
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USER BROPHY 



USER ALUSIC 





MB-S^54a-B0 



Figure 5-2: Library Group 

In Figure 5-2, users KOHN, ALUSIC and BROPHY are not directory group 
members of the same group; however, they are all user group members in 
the same group (group 2). User KOHN can access directory <KOHN> 
according to the owner protection field and can access directories 
<SUBROUTINES>, <TAPE-TESTS> , and <MACROS> according to the group 
protection field. KOHN can access <BROPHY> and <ALUSIC> according to 
the "world" protection field. Although the arrows have not been drawn 
from users BROPHY and ALUSIC, their access privileges are the same as 
KOHN's. 
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TEACHER WILEY 




MR-S-549-B0 



Figure 5-3: Teacher-Student Group 

In a teacher-student group (Figure 5-3) , the teacher, WILEY, is a 
member of the group as a USER, while the directories <HURLEY>, <HALL>, 
<MILLER>, and <RUSSELL> are <DIRECTORY> members. The teacher, WILEY, 
can access the files in the directories <HURLEY>, <HALL>, <MILLER>, 
and <RUSSELL> according to the group protection. The students whose 
logged-in directories are in this group as <DIRECTORY> members can 
access the files in <WILEY> according to the protection set for all 
users, because only their directories are members of the group; they 
are not members of the group as users. 
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5.9 GIVING USERS SPECIAL CAPABILITIES 



You can give special capabilities to certain 
OPERATOR, CONFIDENTIAL, MAINTENANCE, IPCF, 
and ABSOLUTE-ARPANET-SOCKETS. Each capabilit 
is placed in the user's directory paramete 
change the directory. The person who enter 
user's directory must have that capabili 
enabled at the time the capability is ente 
parameter list. You should grant these capab 
absolutely need them. Table 5-3 lists all th 
and a brief description of their function. 



users; they are WHEEL, 
ENQ-DEQ, ARPANET-WIZARD, 
y that you give to a user 
r list when you create or 
s the capability in a 
ty himself, and have it 
red into the directory 
ilities only to users who 
e available capabilities 



Table 5-3: Special Capabilities 



Capability 


Description 


WHEEL 


Allows the user to modify any system 
parameters or data. In particular, the 
WHEEL capability is needed if the user 
wants to give the "EEDDT or "EQUIT 
commands. 


OPERATOR 


Allows the user all capabilities required 
to control the system. The user cannot, 
however, give the "EEDDT or "EQUIT 




commands. 


CONFIDENTIAL 


Allows the user to obtain accounting 
information for another user's job. 


MAINTENANCE 


Allows the user (usually the field service 
representative) to perform certain 
maintenance functions, but he cannot give 
the "E commands. 


IPCF 


Allows the user to perform the privileged 
functions of IPCF. (Refer to the TOPS-20 
Monitor Calls Reference Manual.) 


ENQ-DEQ 


Allows the user to perform global 
ENQUEUE/DEQUEUE functions. (Refer to the 
TOPS-20AN Monitor Calls User's Guide.) 


ARPANET-WIZARD 


Allows the user to perform certain ARPANET 
privileged functions. (Refer to the 
TOPS-20AN Monitor Calls User's Guide.) 


ABSOLUTE-ARPANET- 
SOCKETS 


Allows the user to place absolute socket 
numbers in his programs. 


ARPANET-ACCESS 


Allows the directory owner to establish 
ARPANET network connections,. 


DECNET-ACCESS 


Allows the directory owner to establish 
DECNET network connections. 
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With the exception of WHEEL and OPERATOR, these capabilities are not 
listed in a format where having one capability means you also have the 
capabilities listed below it. The user who has WHEEL capabilities can 
perform the OPERATOR, CONFIDENTIAL, MAINTENANCE, IPCP, and ENQ-DEQ 
functions. The user who has OPERATOR capabilities can also perform 
these privileged functions with the exception of the "EEDDT and "EQUIT 
commands. But the user who has CONFIDENTIAL capabilities can only 
perform functions that are allowed by this capability; that is, he 
cannot perform MAINTENANCE, IPCF, ENQ-DEQ, ARPANET WIZARD, and 
ABSOLUTE ARPANET SOCKETS functions, unless he has been given the 
individual capability. The same principle is true for the remaining 
capabilities. 

Also, you are giving capabilities to a user, not the user's directory. 
Therefore, if user HALL has WHEEL capabilities, other users who 
connect to or access the directory <HALL> do not obtain WHEEL 
capabilities. However, if they log in as user HALL, they will obtain 
HALL's capabilities. For this reason, users with special capabilities 
(especially WHEEL and OPERATOR) should be especially careful in 
selecting and protecting their passwords. They should be encouraged 
to change them often, and to use passwords that cannot be readily 
guessed. 



5.10 PRINTING DIRECTORY INFORMATION 

The ULIST program prints information about directories on the system 
and is described in the TOPS-20 Operator' s Guide. In addition to 
listing information about each directory, the ULIST program can list 
information about groups, capabilities, and related information. 

The LIST subcommand of the ~ECREATE command prints information about 
the directory or user name you are currently creating, and the "EPRINT 
command also prints the information on an individual basis. 
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CREATING ACCOUNTS 



The TOPS-20 accounting facility allows you to assign and charge 
computer usage to valid accounts. It provides you with a means for 1) 
adding security to your system, 2) determining charges for computer 
usage and billing users by account, and 3) associating classes with 
accounts for use by the class scheduler. You can use account 
validation for one or all of these reasons. 

One or more accounts can be assigned to a user for specific tasks and 
validated each time they are used. All accounting data, including 
records of CPU time, structures used, and peripherals used under a 
valid account, are stored in a usage file and can be used later for 
reports and billing. 

This chapter describes how to set up the system to use accounts and 
establish an accounting data base. The TOPS-20 USAGE File 
Specification describes how to create accounting reports from the 
Usage file and establish billing procedures. The following sections 
include: 

• How to set up your system to use accounts 

• How to select an accounting scheme 

• How to use your accounting scheme and create the necessary 
base account and subaccount files 

• How to run the account generator program (ACTGEN) , which 
takes these account data files and creates the accounting 
data base 

• What the operator can do if the accounting data base does not 
work properly 

• How to initialize your system to start validating accounts 



6.1 SETTING UP THE SYSTEM TO USE ACCOUNTS 

6.1.1 Enabling or Disabling Account Validation 

During software installation, you can specify whether you wish to 
create the account data base and validate accounts. You can make an 
entry in the n-CONFIG.CMD file that specifies either DISABLE 
ACCOUNT-VALIDATION or ENABLE ACCOUNT-VALIDATION. If you do not make 
an entry in the n-CONFIG.CMD file for accounting, the system assumes 
ENABLE ACCOUNT-VALIDATION. 
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If you enter DISABLE ACCOUNT-VALIDATION, meaning you do not wish to 
use the account validation facility, the system checks each account 
only for length. The purpose of the check is to ensure that the 
maximum number of alphanumeric characters has not been exceeded in 
each account. No other checking is performed. If a user attempts to 
use or create an account greater than 39 characters, the system simply 
truncates the entry to the 39-character maximum. 

If you have instructed the system to ENABLE ACCOUNT-VALIDATION but 
have not yet created an account validation data base, you receive a 
warning on the console terminal (CTY) when the system starts 
operation. The message is: 

<SYSTEM>ACCOUNTS-TABLE.BIN NOT FOUND - ACCOUNT VALIDATION IS DISABLED 

The system continues its normal operation; however, no accounts are 
validated (except for length checking) until you create the necessary 
account data files and run the account generator program (ACTGEN) to 
create your account data base. 

You should not receive the above warning message if you have created 
your account data base prior to bringing the system up for operation. 
Users can log into the system using their valid accounts. 



6.1.2 Setting up Account Validation with Existing Files 

If you are using account validation on a system that already has 
files, the accounts for these existing files should be updated before 
account validation is enabled in the n-CONFIG.CMD file. Notify the 
users who created these files to change the existing account on every 
file to their new account(s). This procedure ensures accurate billing 
immediately after the system is brought up and that daily DUMPER tapes 
contain files with valid accounts. This means that if you must 
restore files from a backup tape, the correct account for each file is 
properly restored; therefore, the disk file storage continues to be 
accurately charged. (Refer to the TOPS-20 Operator's Guide for the 
procedure to follow if all files do not get updated.) 



6.1.3 Setting up the System for Accounting Shift Changes 

The accounting facility also allows you to change your billing rates 
for system usage at selected times during the day. This action is 
called an accounting shift change. Accounting shift changes are 
selected by day-of-week and time-of-day. 

You must enter the appropriate commands in the n-CONFilG.CMD file to 
I initiate accounting shift changes. The n-SETSPD program reads these 
commands each time the system is reloaded. The format of the command 
placed in the n-CONFIG.CMD file is: 

CHANGE time days-of-week 
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You can use any format for the time and day, that is, 1500, 15:00, 
3:00pm, MONDAY, MON. Or, you can use the keywords ALL, WEEKENDS, and 
WEEKDAYS. The default for days-of-week is ALL. The following is a 
typical set of commands that may appear in the n-CONFIG.CMD file: 

CHANGE 9:00 WEEKDAYS 

CHANGE 10:00 WEEKENDS, MONDAY 

CHANGE 12:00 TUESDAY, THURSDAY, SAT 

CHANGE 17:00 

The CHANGE (ACCOUNTING SHIFT NOW) command to the CHKPNT program 
provides you with a means of changing shifts during system operation. 
This command causes an accounting session to end and a new accounting 
session to begin for all active jobs on the system.- Refer to the 
TOPS-20 Operator' s Guide for a description of all the commands that 
can be given to the CHKPNT program. 



6.2 SELECTING AN ACCOUNTING SCHEME 

The first thing you must do before you create account data files is 
set up an accounting scheme. This procedure includes deciding which 
accounts you wish to create, their expiration dates if you are going 
to open and close accounts, the names of the users who can use (or 
charge to) those accounts and, if you are using the class scheduler, 
the scheduling class associated with each account. 

The TOPS-20 account validation facility allows several levels of 
project administration in a group of accounts having the same base 
account. For example: 



DENVER -» 



Base Account 



OVERHEAD 



• Subaccount 



The accounts you would create using the above example are: 

DENVER 
DENVER. CHEM 
DENVER. CHEM. OVERHEAD 
and 
DENVER. CHEM. LAB-12 

In this example, users at Denver University taking a particular lab 
course in chemistry (e.g., 12) would log in and charge to their 
assigned account, DENVER. CHEM. LAB-12. 
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All accounts that you assign to users can have a maximum length of 39 
alphanumeric characters. The system allows you to use a hyphen (-) 
within the accounts you create (e.g., LAB-12) , but no other 
punctuation (including spaces) can be used. Note that the system uses 
the period (.) as a delimiter to separate each part of multi-level 
accounts and the period is counted as one of the 39 characters. 
Therefore, DENVER. CHEM. OVERHEAD is a user account with 20 characters. 

The type of accounting scheme you use depends on the form of project 
administration you have at your installation. Multi-level accounts 
are usually created through a form of project administration similar 
to that used when allowing certain users (perhaps heads of 
departments) to create subdirectories. (Refer to Chapter 5, Creating 
Directories.) Remember that subdirectories are just like any other 
directory. Therefore, users must have accounts to log into their 
directory. 

Generally, all files that contain data pertaining to base accounts are 
created by you or the operator, and all files that contain subaccount 
data are created by one, or perhaps more than one, project 
administrator. A project administrator, for example, might be the 
head of the Chemistry Department. (This could be the same person who 
handles the subdirectory creation for a group or groups of users.) 
Allocating the subaccount file creation to a project administrator 
allows you to collect or budget for one base account (e.g., 
DENVER. CHEM) and not be directly concerned with the subaccounts. In 
the example, the head of the Chemistry Department is responsible for 
creating the subaccount files under DENVER. CHEM. , that is, LAB-12 and 
OVERHEAD. Section 6.3 describes how to create these account data 
files using a sample accounting scheme. 

Figures 6-1 and 6-2 illustrate several ways that you can set up your 
accounting scheme. Figure 6-1 is a simple scheme that a small 
organization might use. It also allows you, as system manager, to 
have complete control over all accounts because you are aware of every 
account assigned. 
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Figure 6-1 shows that the manager at Correct Da 
to set up one base account for Correct Data a 
each customer using his system. He used the c 
accounts. All the people who use the sys 
charge their computer usage to the Correct Data 
Unionbank, L & P Food, and Town Square Magazine 
those people who will be using the system from 
These are the only people who will be able to 
and charge to their assigned account. The man 
also planned expiration dates for each customer 



ta Company has decided 
nd one base account for 
ustomer name for the 
tem at Correct Data can 

account, CORRECT-DATA. 

submitted the names of 
their respective sites. 

log in from their site 
ager at Correct Data 

account. 



SAMPLE COMPANY: Correct Data 
TYPE OF BUSINESS: Timesharing House 
PRIMARY MODE OF OPERATION: Batch 



ACCOUNT CORRECT-DATA 

USER Hudson, Holland, Gerard, Gionet, King, Kelly, Kohn 

(Note: These 7 people are all the users at Correct Data) 



ACCOUNT UNIONBANK 

USER Warriner, Bloomstran, Prest, Pendergast 

EXPIRES June 1,1986 



ACCOUNT LP-FOOD 

USER Schied, Queeny, Smith 

EXPIRES July 1, 1986 



ACCOUNT TOWN-SQUARE 
USER Markley, Gerhard, Dole 

EXPIRES July 15, 1986 



Figure 6-1: Accounting Scheme 1 



Using the same sample company, Figure 6-2 shows how a simple 
accounting scheme of this type can be expanded into a form of project 
administration. Here, Correct Data and one of its customers, 
Unionbank, broke down the base accounts into subaccounts. 

Because Correct Data bills Unionbank for all its computer usage as one 
account, the manager at Correct Data is not concerned with how 
Unionbank subdivides its account, and is probably not aware of the 
subaccounts at Unionbank. The manager at Unionbank, however, is 
concerned with the computer usage costs incurred by each department 
within his company. He supplies Correct Data with the name of the 
file that contains his subaccount information. 
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SAMPLE COMPANY: Correct Data 
TYPE OF BUSINESS: Timesharing House 
PRIMARY MODE OF OPERATION: Batch 



ACCOUNT CORRECT-DATA 
USER Hudson, Holland 


SUBACCOUNT 
USER 


PAYROLL 
Gerard, Kelly 


SUBACCOUNT 

USER 

EXPIRES 


OVERHEAD 
Gionet, Kohn, Kelly 
December 31, 1986 


SUBACCOUNT 
USER 


PROGRAMMING 
King, Carlson 


ACCOUNT UNION BANK 
USER Warriner 


SUBACCOUNT 
USER 


TRUST 
Bloomstran 


SUBACCOUNT 
USER 


LOANS 
Prest 


SUBACCOUNT 
USER 


MSTRCHG 
Prest, Pendergast 


SUBACCOUNT 
USER 


PAYROLL 
Bloomstran 



Figure 6-2: Accounting Scheme 2 



Section 6.3 describes how to enter the information for Figures 6-1 and 
6-2 into files that are used to create an account data base. 



6.3 CREATING AN ACCOUNT DATA BASE 

Sections 6.3.1 through 6.3.3 describe how to use your selected 
accounting scheme and create the necessary files for your data base. 
Specifically, these sections include how to enter accounting data into 
files, how to run the account generator program (ACTGEN) to create the 
data base, and what to do if an error occurs. 
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6.3.1 Entering Accounting Data into Files 

Base and subaccount files are created using a text editor. The format 
below shows the combination of entries you can make in accounting 
files using the CREATE command. Each file you or a project 
administrator creates can contain one or more accounts. Each account 
can point to one subaccount file, where additional account information 
is stored pertaining to that account. Following the format is a 
summary of the valid commands in an account file. 

ACCOUNT DATA FILE FORMAT 

@CREATE (FILE) <d irectory> filename .type 
INPUT: filename. type. 1 

00100 ACCOUNT account/SUBACCOUNT:dev:<dir>f ilename.type- 

00200 /CLASS :n/ALLOW:n,n 

00300 USER name, name, name, .. . 

00400 DIRECTORY dev:<d irectory> 

00500 GROUP (ON STRUCTURE) dev :/USER: user group number 

00600 GROUP (ON STRUCTURE) dev :/DIRECTORY :d irectory group number 

00700 <ESC> 

*EU 

< filename. type. 1> 

In addition to the above entries, each entry in the file can have an 
expiration date in the form: 

/EXPIRES :dd-mm-yy hh:mm 

This switch indicates when the account will no longer be valid for 
that entry in the file. For example: 

USER namel,name2/EXPIRES: 10-JAN-86,name3,name4 

In the above example, name2 can no longer use this account after 10 
January 1986. Namel, name3, and name4, however, can continue to use 
the account beyond that date. You could also place the switch 
immediately following the USER entry. For example: 

USER/EXPIRES: 10-JAN-86, namel, name2, name3, name4 

This format specifies that none of the users in the list can use the 

account after a certain date. The account, however, remains open, and 

you can place another list of users in the file who can use the 
account. 

Table 6-1 summarizes the account data file commands. You can type the 
entire command, or just the characters necessary to distinguish one 
command from another. For example, ACCOUNT can be typed as AC. 

Because the ACCOUNT command has several modifiers, you may have to 
continue typing the modifiers on the next line. To do this, use a 
hyphen at the end of the line and continue typing the ACCOUNT 
modifiers on the next line. For example, 

0100 ACCOUNT TEST/SUBACCOUNT:SYSA:<MARK> ACCOUNT.TXT- 
0200 /CLASS: 2/ALLOW: 1,3 
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Table 6-1: Summary of Account Data File Commands 



Command 



Description 



ACCOUNT 



/SUBACCOUNT: 



/CLASS :n 



Specifies the name of the account that you or 
a project administrator wish to assign. 

Note: The ACCOUNT command must be the first 
entry in an account data file because all 
subsequent entries up to the next ACCOUNT 
entry are modifiers. 

Modifies the ACCOUNT command. It includes the 
specification of the file where additional 
data for the account can be found. 

Note: The ACCOUNT command accepts only one 
/SUBACCOUNT :modifier. 

Example: One of your accounting files 
contains the following commandls. 

ACCOUNT CORRECT-DATA/SUBACCOUNT : 

<GERHARD>ACCT.TXT 

ACCOUNT UNIONBANK/SUBACCOUNT: 

<WARRINER>ACCTG.TXT 

ACTGEN looks in <GERHARD>ACCT.TXT for more 
account data for the account CORRECT-DATA, 
and it looks in <WARRINER>ACCTG.TXT for more 
data for account UNIONBANK. 

Modifies the ACCOUNT command and is used in 
conjunction with the class scheduler. It 
specifies the scheduling class that is valid 
for this account. For example, 

ACCOUNT CHEM-207/CLASS:3 

means that class 3 is valid when using the 
account CHEM-207. ACTGEN places this 
information in the system's accounting data 
base for use by the class scheduling 
routines. Use the /CLASS:n switch only if you 
have selected to specify class scheduling by 
account. (Refer to Section 10.1 for a 
complete description of using the class 
scheduler by account.) 

When a user gives an account that does not 
have a valid class associated with it, the 
system uses the default class, class 0. If 
the account has a class associated with it, 
that class is used. The percentage of CPU 
time that classes can receive is defined in 
the n-CONFIG.CMD file. 

To use class scheduling by account, you must 
have: 

• made the appropriate entries in the 
n-CONFIG.CMD file. 
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Table 6-1: Summary of Account Data File Commands (Cont.) 



Command 



Description 



/ALLOW :n,n 



USER 



• updated your ACCOUNTS.CMD file (and 
subaccount files) to specify the classes 
that are associated with each account. 

• run ACTGEN with the INSTALL command to 
update the ACCOUNTS-TABLE.BIN file. 

• given the ENABLE CLASS-SCHEDULER command 
to OPR or brought the system down and back 
up again to start class scheduling. 



Modifies the ACCOUNT command and is used in 

conjunction with the class scheduler. It 

allows you to delegate the assigning of 
classes to subaccounts by project 

administrators. It specifies the class or 

classes that can be used by subaccounts of 
this account. For example, 

ACCOUNT CHEM/SUBACCOUNT: <ABOM0RE.TXT- 
/CLASS : 2/ALLOW: 1 , 3 

means the CHEM account is in class 2, and 
that subaccounts created under CHEM can be in 
either class 1 or class 3. If no /ALLOW 
switch is given, the administrator is not 
restricted to using certain classes and, 
therefore, can give the subaccounts any 
class. For example, the administrator can 
give them the same class as the superior 
directory. The /ALLOW switch is useful when 
you want the superior account to be in 
perhaps a higher percentage class than its 
inferior accounts. Remember that if the 
administrator does not give a /CLASS switch 
to the subaccount, users who log into or 
change to this subaccount will be in class 0. 

Specifies one user or the list of users who 
are allowed to use this account. 

Specifies that an account is valid for all 
users on a system. The * is a special 
argument to the USER command. 

Example: One Instance when you might use * is 
if you have not established an accounting 
scheme but would like to allow users to log 
into the system. You could set up one account 
and use the * to indicate that all users can 
use that account. 

You could also use the * as follows: 

ACCOUNT MATH-101 
USER: MATH.* 
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Table 6-1: Summary of Account Data File Commands (Cont.) 



Command 



DIRECTORY 



GROUP 



/USER:nnn 
/DIRECTORY :nnn 



Description 



This means that all users with a user name 
beginning with MATH can use the MATH-101 
account. For example, the users assigned the 
user names MATH. SMITH, MATH. JONES, and 
MATH. BROWN can all use this account. 



Specifies a directory n 
the account is valid fo 
access to the director 
users to create or stor 
or groupwide director 
to an "overhead" accoun 
own account. The us 
directory could be a 
project administration 
prevents users from 
storage in files-only d 



ame. It indicates that 
r anyone with write 
y. This feature allows 
e files in systemwide 
ies and to charge them 
t different from their 
age charged to this 
bsorbed by system or 
This command also 
being charged for file 
irectories. 



Note: The DIRECTORY command also accepts a 
form of the wildcard entry. The valid forms 
are: *:<*>, dev:<*>, or *:<dir>. The asterisk 
indicates that users with write access to any 
of the directories matching the wildcard 
entry may charge their file creation to a 
certain account. 

Example: The file that contains account data 
for account CORRECT-DATA. UNIONBANK. FUND has 
the entry: 

DIRECTORY PS:<FORLIB> 

This entry means that anyone with write 
access to directory <FORLIB> can use the 
account CORRECT-DATA. UNIONBANK. FUND when 
storing files there. 

Specifies that an account is valid for use by 
certain user and directory groups on a 
structure. (Refer to Section 5.8 for a 
description of groups.) 

Modifies the GROUP command and can be used in 
any combination, (nnn is a decimal user or 
directory group number.) /EXPIRES: can be 
placed after either modifier to indicate when 
an account becomes invalid for use by the 
group. 

Note: Using the GROUP command is helpful if 
many people are eligible to use an account. 
Specifying their group number (if they are in 
a group) eliminates typing a long list of 
names incorrectly. 
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6.3.2 Sample Data Files 

The examples below show how you could enter the information in Figures 
6-1 and 6-2 into account data files. The first example shows the data 
file for Figure 6-1. Tabs and comment lines beginning with an 
exclamation point (!) can be used within the file for ease in reading 
or formatting the file. This file in particular contains all the base 
accounts and should be stored in your directory. You may find it 
easier when you run ACTGEN if you name the file 
ACCOUNTS.CMD. ACCOUNTS.CMD is the default file that the TAKE command 
under ACTGEN looks for. (Refer to Section 6.3.3 for running ACTGEN 
and giving the TAKE command.) 

©CREATE (FILE) <HUDSON>ACCOUNTS . CMD<RET> 
Input: ACCOUNTS. CMD.l 

00100 IThis file contains definitions of top-level accounts<RET> 

00200 ACCOUNT CORRECT-DATA<RET> 

00300 USER Hudson, Holland, Gerard, Gionet<RET> 

00400 USER King, Kelly, Kohn<RET> 

00500 ACCOUNT UNIONBANK/EXPIRES;l-JUN-86<RET> 

00600 USER Warriner,Bloomstran,Prest,Pendergast<RET> 

00700 ACCOUNT LP-F00D/EXPIRES:1-JUL-86<RET> 

00800 USER Schied,Queeny,Smith<RET> 

00900 ACCOUNT TOWN-SQUARE/ EXP I RES: 15-JUL-86<RET> 

01000 USER Markley, Gerhard, Dole<RET> 

01100 <ESC> 

*EU<RET> 

<ACCOUNTS.CMD.l> 

NOTE 

Lines 300 and 400 contain all the users at Correct 
Data. However, you would not use the asterisk (*) 
because it would enable all the users of the system, 
including the users at Unionbank, L & P Food, and Town 
Square to charge to the CORRECT-DATA account. 

Figures 6-3 and 6-4 show what information to enter into base and 
subaccount files for Figure 6-2. Each block in Figures 6-3 and 6-4 
contains information to be entered into a separate file. Some of the 
blocks contain subaccount (/SUB:) entries that point to other files 
containing more information about that particular account. 

Figure 6-3 shows which entries to make for account CORRECT-DATA and 
its subaccounts (the top half of Figure 6-2.) 

Figure 6-4 shows which entries to make for account UNIONBANK and its 
subaccounts (the bottom half of Figure 6-2.) Note that all the base 
account entries for both Correct Data and Unionbank are contained in 
the file <HUDSON>ACCOUNTS.CMD. 
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Figure 6-3: Correct-Data Accounting Files 



< GERARD > ACCOUNT. TXT 
ACCOUNT PAYROLL 
USER Gerard, Kelly 



< HUDSON > ACCOUNTS. CMD 

ACCOUNT CORRECT-DATA/SUB: < GERARD > ACCOUNT. TXT 

USER Hudson, Holland 

ACCOUNT CORRECT-DATA/SUB: < GIONET > ACCT. TXT 

ACCOUNT CORRECT-DATA/SUB: < KING > ACCTG.TXT 



< GIONET > ACCT. TXT 

ACCOUNT OVERHEAD/EXPIRES:31-DEC-86 

USER Gionet, Kohn, Kelly 



< KINO ACCTG.TXT 
ACCOUNT PROGRAMMING 
USER King, Carlson 



NOTES 
The accounts that will be created are: 

CORRECT-DATA. PAYROLL 
CORRECT-DATA.OVERHEAD 
CORRECT-DATA. PROGRAMMING 
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Note that users Hudson and Holland can use any account number 
that begins with CORRECT-DATA, but user Gerard can use only 
the account CORRECT-DATA. PAYROLL. User Kelly can use the 
accounts CORRECT-DATA. PAYROLL and CORRECT-DATA. 
OVERHEAD. 

The file type for account data files is optional. Your project 
administrators can use any file type, e. g. , .TXT, .CMD or .ABC. 



Figure 6-4; Unionbank Accounting Files 



< HUDSON > ACCOUNTS. CMD 

ACCOUNT CORRECT-DATA/SUB:<WARRINER>ACCOUNT.TXT 

USER Hudson 



<WARRINER> ACCOUNT. TXT 

ACCOUNT UNION BANK/SUB: < BLOOMSTRAN > ACCT. TXT 

USER Warriner 

ACCOUNT UNIONBANK/SUB: < PREST > ACCO. TXT 

ACCOUNT UNIONBANK/SUB: < PENDERGAST> MCA.TXT 



I 



< BLOOMSTRAN > ACCT. TX7 
ACCOUNT TRUST 
USER Bloomstran 

ACCOUNT PAYROLL 
USER Bloomstran 



< PREST > ACCO. TXT 

ACCOUNT LOANS/SUB:< THOMAS > LO.TXT 

USER Prest 

ACCOUNT LOANS/SUB:< MILLS > DATA. TXT 



< PENDERGAST > MCA. TXT 
ACCOUNT MSTRCHG 
USER Pendergast, Prest 
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< THOMAS > LO.TXT 
ACCOUNT INSTAL 
USER Thomas 

ACCOUNT CORP 
USER Thomas, Mills 



NOTE 
The accounts that will be created are: 

CORRECT-DATA. UNIONBANK. TRUST 
CORRECT-DATA. UNIONBANK. PAYROLL 
CORRECT-DATA. UNIONBANK. MSTRCHG 
CO R R ECT-DATA. UNION BAN K. LOANS. I NSTAL 
COR R ECT-DATA. UN I ON BAN K. LOANS. CORP 
CORRECT-DATA. UNIONBANK. LOANS. COMM 



< MILLS > DATA. TXT 
ACCOUNT COMM 
USER Mills 
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6.3.3 Running the ACTGEN Program 

After you create the base account files and the project administrator 
notifies you that all his subaccount files are complete, you can tell 
the operator to run the ACTGEN program. ACTGEN takes the accounting 
information in these files and creates an account validation data 
base. It is through this data base that the monitor validates all 
accounts entered by the users of your system. ACTGEN is a privileged 
program, so you must enable WHEEL or OPERATOR capabilities before 
giving the ACTGEN command. The command appears as follows: 

@ENABLE (CAPABILITIES) <RET> 

$ACTGEN<RET> 

ACTGEN> 

Valid commands that can be given to ACTGEN are HELP, EXIT, TAKE, 
CTRL/A, and INSTALL. 

The HELP command lists information to assist you when running the 
ACTGEN program. 

The EXIT command terminates the program and returns you to the TOPS-20 
command level ($) . 

The TAKE command accepts as its argument either a file specification 
or a carriage return. A carriage return defaults to your connected 
directory and the filename ACCOUNTS.CMD. If you do not name your base 
account file ACCOUNTS.CMD, the file you specify should be the one that 
contains your base account information and points to all the existing 
subaccount files. The TAKE command tells ACTGEN to look in the 
specified (or default) file for account information. It also tells 
ACTGEN to look at any subaccount file specifications for additional 
information pertaining to the account(s) in the base account file. 
Using Figures 6-1 and 6-2, the manager, Hudson, would specify the TAKE 
command as follows: 

©ENABLE (CAPABILITIES) <RET> 

$ACTGEN<RET> 

ACTGEN> TAKE (COMMANDS FROM FILE)<RET> 

If the manager in these examples had named his base account file 
MACCT.TXT, he would specify the TAKE command as follows: 

ACTGEN> TAKE (COMMANDS FROM FILE) <HUDSON>MACCT. TXT<RET> 

CAUTION 

If the data files that are pointed to by your base 
account file are located on structures other than the 
public structure, be sure the required structures are 
mounted. Otherwise, the ACTGEN program will fail on 
those accounts that have subaccount files on unmounted 
structures. 

ACTGEN takes all the information specified in the account files, forms 
the valid accounts, and creates a new version of the file 
ACCOUNTS-TABLE.BIN in the directory where ACTGEN is running. Each 
time the ACTGEN program is run successfully, a new version of this 
file is created. 
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While ACTGEN is creating the data base file, it checks for duplicate 
entries, e.g., two accounts of the same name, and the length of the 
accounts. If an error occurs, an appropriate message is printed on 
the terminal where ACTGEN is running, but the program continues to 
build the data base, using only the accurate data. You should make a 
note of the error on an error log sheet that you have prepared and 
later correct the appropriate files using an editor. 

ACTGEN also checks expiration dates. If two or more expiration dates 
are given for the same entry in a file, the system uses the earliest 
date. For example: if you specify May 15, 1985 as the expiration 
date for account MATH and your project administrator specifies August 
30, 1985 for the account MATH. LAB-201 , the system will stop validating 
all accounts beginning with MATH as of May 15, 1985. 

You can press CTRL/A while ACTGEN is running to stop the program and 
return to ACTGEN command level. The data files are closed and no new 
version of the data base file ACCOUNTS-TABLE.BIN is created from this 
session. 

The INSTALL command starts account validation. When you enter this 
command, ACTGEN copies the ACCOUNTS-TABLE.BIN file in your connected 
directory (or the directory where ACTGEN created the file) to 
<SYSTEM>ACCOUNTS-TABLE.BIN on the public structure and enables account 
validation using this new data base. 

Because the new version of ACCOUNTS-TABLE.BIN is kept in the directory 
where ACTGEN was run and not in the directory <SYSTEM>, you have a 
means of correcting any errors that might occur without disturbing the 
version currently running in the <SYSTEM>ACCOUNTS-TABLE.BIN file on 
the public structure. You can give the INSTALL command after you have 
corrected any problems. 

If you do not receive any errors while ACTGEN is creating the data 
base file (ACTGEN has successfully completed the accounting file and 
you receive the ACTGEN prompt) , you can give the INSTALL command 
immediately. 

You should keep track of which version of the 
<SYSTEM>ACCOUNTS-TABLE.BIN file you are using. A log book that 
contains the date that ACTGEN was run and the version number of the 
data base file is helpful should a system problem occur and you are 
not sure of which data base file you were using. To find out which 
version you are using, enable capabilities and give the DIRECTORY 
command for <SYSTEM>ACCOUNTS-TABLE.BIN on the public structure. The 
generation number indicates the version that is presently running. 
The system looks in the current data base file each time it validates 
a given account. 



6.3.4 Data Base Failures/Recovery 

If your accounting files were set up inaccurately, or you entered 
random incorrect data into the data base file, account validation will 
not work properly. You are aware of this because users cannot log in 
and/or use accounts that are normally valid for them. Therefore, the 
account OPERATOR is set up for the user OPERATOR and is always valid. 
The operator can log into <OPERATOR> with the OPERATOR account, fix 
the files that are in error, and run ACTGEN to get account validation 
working again. 
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6.4 VALIDATING ACCOUNTS 

An account is validated when a user gives any one of the following 
TOPS-20 commands. 

• LOGIN - A user must have a valid account to successfully log 
into the system 

• SET ACCOUNT (TO) argument 

• Any queue commands, for example, PRINT, SUBMIT, if the 
account is different from the currently validated account 

• SET FILE ACCOUNT (OF FILES) arguments (TO) argument 

• File creation with an explicit account 

The system records the computer time used for valid accounts. This 
includes CPU time, time used per structure , [1] and peripherals used 
per job, that is, the number of pages printed on the line printer, 
tape mounts, tape records read/written, card reader usage, and disk 
storage. The computer usage incurred by each account is stored in the 
accounting USAGE. OUT file. This file is used for reports and billing. 
(Refer to the TOPS-20 Usage File Specification for information about 
reading and using this file) . 

How often you run ACTGEN and create a new data base f$le depends on 
how frequently you change your accounts. If you expect to have 
frequent changes (e.g., opening and closing accounts), you may want to 
establish a standard time each week to run ACTGEN. Your 
administrators should inform the operator when changes are made to 
their subaccount files. 

NOTE 

Once ACTGEN is run and the data base file has been 
created, you can dump all the account files to 
magnetic tape and conserve some of your disk space. 
You must copy the files to disk the next time you need 
to run the ACTGEN program. 



[1] To account for the time used on a structure, you must set the 
structure as REGULATED. Refer to the TOPS-20 Operator's Guide 
for a description of REGULATED and NONREGULATED structures. 
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CHAPTER 7 
SYSTEM BACKUP PROCEDURES 



All the di£>k packs on your system must be backed up on magnetic tape. 
This procedure provides both a permanent record of the contents of the 
disk and a precautionary measure in the event a disk pack and/or its 
contents are destroyed. On the first day of operation, start a system 
backup procedure that includes: 

1. Saving all the files in all the directories on all structures 

2. Saving the directory parameters and critical system programs 

3. Saving the front-end file system (one time only) 

These procedures should become a part of the operator's scheduled 
duties. 

It is important to start backing up the system immediately after 
installation. If you follow the backup procedures as they are 
outlined here and in the TOPS-20 Operator's Guide, you can restore the 
file system quickly and easily should a mishap occur. 

DUMPER 

The following sections discuss using the DUMPER program to save files. 
Make sure when you restore these files with DUMPER that you are 
running the correct version of DUMPER with your TOPS-20 monitor and 
that the tape version is compatible with the software. Otherwise, 
directory passwords could become unusable and you may have to manually 
respecify them with the BUILD command. Refer to Section 11.2, 
Password Encryption, for details. In addition, project-programmer 
numbers, supported in TOPS-20 version 6, may not be restored at all 
with incompatible versions of the software. 

In a CFS configuration, DUMPER must run on the system to which the 
tape drives are attached. 

To simplify backup and restore operations, you can create DUMPER 
command files for the operator. Rather than type a list of commands 
to DUMPER, the operator can then just give the TAKE command with a 
command file name as an argument. DUMPER will sequentially execute 
commands contained in the file. 

The TOPS-20 User Utilities Guide and the TOPS-20 Operator's Guide 
discuss the DUMPER program in detail. 
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7.1 SAVING ALL FILES IN ALL DIRECTORIES 

Have the operator run the DUMPER program (with the /FULL-INCREMENTAL 
switch to the SAVE command) to save all files in all directories. 
This procedure includes saving all the directories on the public 
structure and all the directories on any additional structures you 
have created. You can save all the files (a full dump) or just the 
files that have changed since the last time the operator ran DUMPER 
(an incremental dump) . 

Start a library of the magnetic tapes from the DUMPER operations. 
Each structure should be copied to a separate tape(s) . Each tape 
should be identified with the system model number or name, for 
example, 2060, or System-A, the date, the type of save (full or 
incremental), the name of the structure, and the tape number. (A tape 
set name may replace the tape number, if labeled tapes are used.) A 
typical identification may look like: 



SYSTEM-A (2060) 

30-JANUARY-1985 

Incremental 

ADMIN: 

Tape #1 of 2 



OR: 



SYSTEM-A (2060) 

30-JANUARY-1985 

Full 

ADMIN: 

Tape #3 of 3 



In addition to keeping the tapes, keep the listing of their contents. 
(The operator includes a command to DUMPER to list the contents of the 
magnetic tapes on the line printer.) These DUMPER log files can be 
conveniently kept in a binder with the most recent listing on top. 
Identify each binder with the system model or name, for example, 2065 
or System-A. (Chapter 9, System Problems/Crashes describes how to use 
these log files to restore directories and files.) 

Tell users that backup files do exist and post the times when the 
operator normally creates the backup tapes. Many system managers do 
not allow users to enter the computer room to mount and use the tapes 
themselves. 

NOTE 

The DUMPER program DOES NOT save the files in the 

console front-end file system. If you lose these 

files, you must restore them from the floppy disks. 
(Refer to Section 7.6) 



7.1.1 Full Dumps 

Full dumps contain all the information on the system, with the 
exception of the console front-end files, and can be used to restore 
many of the files that were on the system to their previous state. 
Therefore, full dumps contain a copy of every file in every directory 
on every structure. 

NOTE 

Full dumps are known as FULL-INCREMENTAL dumps. This 
name corresponds to the /FULL-INCREMENTAL switch that 
you give with the SAVE command to DUMPER. 
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7.1.2 Incremental Dumps 

Incremental dumps (using the /INCREMENTAL switch with the SAVE 
command) cause DUMPER to save the files that have never been saved 
(new files) and the files that have been updated since the last time 
an incremental DUMPER operation was performed. Many managers request 
an incremental dump Monday through Thursday and a full dump on Friday. 

The File Descriptor Block (FDB) of each file contains the information 
necessary to determine if the file has been updated since it was last 
saved during an incremental DUMPER operation. A file that has changed 
since the last time it was saved is automatically saved again on tape; 
otherwise, it is passed over. 

The operator should give the INCREMENTAL switch to DUMPER and specify 
each structure one at a time. By running DUMPER for each structure 
individually, the operator can copy each structure onto a separate 
tape. After running DUMPER and copying the structures that are 
presently on-line, the operator should mount any additional structures 
that have been used that day and run DUMPER for them also. 

An incremental dump is faster than a full dump and requires less 
magnetic tape. By specifying a value with the /INCREMENTAL switch, 
you can cause modified files to be written to more than one 
incremental backup tape. This is helpful if you want to be certain 
you can recover the files, even if one of the tapes has data errors. 



7.1.3 Security of Backup Tapes 

It is a good idea to protect the security of your backup tapes. If 
you allow a non-privileged user to mount them, he or she may gain 
access to confidential information, such as other user's data files. 
If the unencrypted passwords were saved along with other directory 
parameters, a technically sophisticated user can retrieve them from 
the DUMPER backup tapes, and thus obtain unauthorized access to the 
privileged accounts on the system. 



7.2 A COMMON BACKUP POLICY 

A common backup policy is outlined below. You can set up your own 
backup policy. 

1. Each day, take an incremental save of the files that have 
changed from the previous day's backup tape. Keep the 
incremental saves until a full save is made, at which time 
you can recycle the incremental tapes. 

2. At the end of the week, take a full save of all the files on 
the system. Keep the full saves for six months, at which 
time you can recycle the tapes into the backup system. 

3. Every six months, take a full save and keep it for a number 
of years, or if you choose, indefinitely. 
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7.3 MAGNETIC TAPE REQUIREMENTS 

You need a supply of magnetic tapes to start a system backup 
procedure. This section provides a guideline for the number of tapes 
you should have on hand for your installation, 
there are 2400 feet per reel of tape. 



It is assumed that 



Type of 
Disk Drive 



RP06 

RA60 

RP04 

RP20 (one 
spindle) 

RP20 (both 
spindles) 

RP20 (one 
spindle) 

RP20 (both 
spindles) 

RP07 

RP07 
RA81 
RA81 



Reels Per 

Drive 



7 
9 
4 
19 

37 

6 

12 

7 

19 

6 

19 



Bits Per 
Inch 



1600 
1600 
1600 
1600 

1600 

6250 

6250 

6250 

1600 
6250 
1600 



Therefore, the number of tapes you stock depends on the type of disks 
at your installation. It also depends on the backup procedure you 
use. For example, if you save your daily incremental tape dumps for a 
longer time than usual, it takes longer to recycle these tapes into 
the backup system, and thus you need more tapes. 

Generally, during the first month after installation, you may need 
approximately 36 (2400 ft.) tapes for each RP06 or RA60, 24 tapes for 
each RP04, 45 tapes (6250 bit/in) or 180 tapes (1600 bit/in) for each 
RP20 disk (2 spindles) , and 72 tapes for each RP07 or RA81 (1600 
bit/in) . 

NOTE 

These estimates assume a magnetic tape blocking factor 
of 1. You can specify a higher blocking factor and 
save much space on your tapes. Before doing this, 
however, there are cautions that you must consider. 
The description of DUMPER in the TOPS-20 User 
Utilities Guide explains how and when you can increase 
blocking factors. 
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7.4 MAKING A SYSTEM CRASH TAPE 

As the name implies, the system crash tape is used to re-create the 
public structure should it become unusable. This tape is created in 
addition to the tapes that contain FULL-INCREMENTAL and INCREMENTAL 
saves of all files and directories. You should make a new system 
crash tape whenever you add a new user, change any directory 
parameters, or make a change (patch) to: 

• The monitor you are running 

• The TOPS-20 Command Processor 

• The DLUSER program 

• The DUMPER program 

Therefore, the crash tape contains only the files necessary to recover 
user directory parameters and important system programs. User files 
themselves are restored from the FULL-INCREMENTAL and INCREMENTAL 
saves of the public structure. 

Label this tape SYSTEM BACKUP TAPE and include the public structure 
name; DECSYSTEM-20 model number or name, for example, 2060 or 
System-B; and the date and time the tape was created. You should 
follow this procedure once a day if users are allowed to change their 
own directory parameters. (Refer to Section 5.7.2 for information 
about allowing users to change directory parameters.) If you are not 
using password encryption (refer to Section 11.2), be careful to 
protect the backup tapes against reading by unauthorized users, 
because all the passwords for your users will be accessible. 

If you are also using mountable structures, you should periodically 
run DLUSER to copy their directory parameters to a file on another 
structure, preferably the public structure. Then, if the mountable 
structure is destroyed, you will be able to recreate the directories. 

NOTE 

I Do not use a labeled tape when creating a System Crash 

I Tape. The reason for this is that the installation 

I software that is used to create the public structure 

I cannot read tape labels. 

The order of files on the crash tape is: 

1. <SYSTEM>MONITR.EXE 

2. <SYSTEM>EXEC.EXE 

3. <SYSTEM>DLUSER.EXE 

4. DLUSER data files 

5. <SUBSYS>DUMPER.EXE 
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6. DUMPER save sets containing the directories; 

<SYSTEM> 

<SUBSYS> 

<NEW-SYSTEM> 

<NEW-SUBSYS> 

<UETP> 

<GALAXY-SUBSYS> 



Notice that the format of this tape is the same as the TOPS-20 
Installation Tape that you used to install the TOPS-20 software. 



7.5 MAKING A CRASH TAPE USING BATCH 

You can create a batch job to make your crash tape or type the 
commands at the operator's terminal. Example 1 shows the standard 
control file that you can submit as a batch job to create this tape. 
In the example, PUB: is the name of the public structure. 

EXAMPLE 1 

SYSTAP Control File 

@TYPE(FILE) SYS:SYSTAP.CTL<RET> 

! Obtain a tape drive 

@MOUNT TAPE TAPE : /WRITE/ LABEL: UNLABELED 

ISystems not using Tape Drive Allocation must replace the 
! MOUNT TAPE command with @ ASSIGN MTA0: and @DEFINE TAPE: 
1 (AS) MTA0: commands. 

@ENABLE (CAPABILITIES) 
@REWIND (DEVICE) TAPE: 

!Save the monitor 

@GET (PROGRAM) PUB : <SYSTEM>MONITR. EXE 

@SAVE (ON FILE) TAPE: 

ISave the TOPS-20 Command Language Interpreter 
@GET (PROGRAM) SYSTEM: EXEC. EXE 
@SAVE (ON FILE) TAPE: 

SSave the DLUSER program 
@GET (PROGRAM) SYS: DLUSER. EXE 
@SAVE (ON FILE) TAPE: 

•Run the same DLUSER program, saving the directory structure 

! on tape 

@ START 

*DUMP (TO FILE) TAPE: 

*EXIT 

SSave DUMPER 

@GET (PROGRAM) SYS : DUMPER. EXE 

@SAVE (ON FILE) TAPE: 
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SRun.the same DUMPER, saving SYSTEM: and SYS: 

@ START 

*TAPE (DEVICE) TAPE: 

*LIST (LOG INFORMATION ON FILE) SYSTAP.LPT 

*SSNAME SYSTEM-FILES 

*SAVE (DISK FILES) PUB : <NEW-SYSTEM>, PUB : <SYSTEM> 

*SSNAME SUBSYS-FILES 

*SAVE (DISK FILES) PUB : <NEW-SUBSYS>, PUB : <SUBSYS> 

*EXIT 

IPrint the DUMPER log file 

@PRINT SYSTAP. LPT/NOTE: BACKUP TAPE 

@DISMOUNT TAPE: 
§ 

ISystems not using Tape Drive Allocation must replace the 
IDISMOUNT TAPE: command with @UNLOAD (DEVICE) TAPE: and 
!@DEASSIGN TAPE: commands. 

To run SYSTAP, submit the batch control file using the TOPS-20 SUBMIT 
• command. 

In the event the public structure becomes unusable, the crash tape can 
now be used by following the instructions in the TOPS-20 KL Model B 
Installation Guide . 

HINT: 

Before you store the crash tape, verify that you have 
made a usable tape. That is, mount the new crash 
tape, follow the instructions in the TOPS-20 KL Model 
B Installation Guide to load the monitor, and use 
DUMPER to get a listing of the tape's contents. 



7.6 SAVING THE CONSOLE FRONT-END FILE SYSTEM 

The DUMPER program does not save the contents of the console front-end 
file system. You can, however, make a backup copy of the file system 
by copying your floppy disks using the front-end program COP (for 
copy) . You should make at least one backup copy of your console 
front-end file system (refer to Section 3.4). 

To run the COP program, follow the steps outlined below. You need not 
stop timesharing when following these steps. 

1. At the operator's console, type CTRL/backslash; the system 
prints PAR>. 

CTRL/backslash 

PAR> 

2. Type MCR COP and press the RETURN key; the system prints the 
COP prompt. 

PAR>MCR COP<RET> 
COP> 
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3. Place the floppy disk to be copied in drive and the floppy 
to contain the new files in drive 1. Be pure to mount the 
floppy disks correctly; this includes checking that the paper 
containing the floppy directory is not accidentally attached 
to the back of the floppy disk. 

4. Type DX1:=DX0: and press the RETURN key; the system starts 
the copying, which takes a few minutes. After the copying is 
complete, the system verifies the copy and prints a message. 
Type CTRL/Z to exit COP. 

COP>DX1:=DX0:<RET> 
COP - STARTING VERIFY 

COP>~Z 

5. To return to TOPS-20 Command Level, type a: CTRL/backslash; 
the system prints PAR>; type another CTRL/Z, or type QUIT and 
press the RETURN key. 

CTRL/backslash I 

PAR>~Z 
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CHAPTER 8 
TAPE STORAGE 



Chapters 1 through 6 deal primarily with setting up and using your 
disk resources. Chapter 7, System Backup, describes how to save all 
the data from your disk structures onto magnetic tape. These tapes 
are the backup tapes that you use to restore directories and perhaps 
entire disk structures if something happens to the disks (refer to 
Chapter 9) . In addition to using magnetic tapes for system backup 
tapes, you can use magnetic tapes to store other types of data and 
save valuable disk space. 

This chapter describes two other uses for magnetic tapes, File 
Archiving and File Migration. It also describes how you can allow the 
system and the operator to control all tape drive assignments, Tape 
Drive Allocation, and how you can set up some or all of your tapes to 
contain labels, Tape Labeling. These uses are described in the 
following order. 

• FILE ARCHIVING 

• FILE MIGRATION 

• TAPE DRIVE ALLOCATION 

• TAPE LABELING 

In addition, the last section of the chapter discusses how to set up 
two DECSYSTEM-20S to share a TX02 tape subsystem. 

File archiving provides you and users of the system with a voluntary 
way to move important files from the disk to magnetic tape for 
long-term storage. These tapes are stored separately from your system 
backup tapes. Users can access these tape files as easily as they 
access files on the disk. When users want to restore archived files 
to disk, they give a command to the TOPS-20 command processor. The 
system then tells the operator which tapes to mount and proceeds to 
restore the files. Section 8.1 describes why you would use the file 
archiving facility, and how to set up your system to archive files to 
magnetic tape. 

File migration provides you with a means of controlling the use of 
disk space. File migration is especially useful if your disk space is 
very low on a particular structure, for example, the public structure. 
This type of disk space control is, for the most part, involuntary on 
the part of the user. Old unused disk files are periodically moved 
(migrated) to magnetic tape by the system operator. Again, you should 
store these tapes separately from your system backup tapes. Users 
still maintain easy access to these files and retrieve them the same 
way as they retrieve archived files. Section 8.2 describes why and 
when you would use the file migration facility and how to set up your 
system to migrate files to magnetic tape. 
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If you use the file archiving or file migration facilities, or both, 

remember that these tapes are in addition to your system backup tapes. 

They are not replacements. You must continue to run the DUMPER 
program and create full and incremental system backup tapes. 

Tape drive allocation provides the system and computer operator with 
complete control over tape drive usage. This means that it prevents 
users from issuing the ASSIGN command and reserving tape drives for 
their jobs. When users issue the MOUNT command, the TOPS-20 Tape 
Drive Allocation system and the operator control the allocation of 
tape drives. You must use the tape drive allocation facility if you 
use tape labeling; however, using tape drive allocation does not 
restrict you to using labeled tapes. 

Tape labeling provides a means of storing label information on the 
tape itself that identifies the tape and described the data on the 
tape. This label information is in an industry standard format so you 
can read and write tapes to be used with differentj computers. Tape 
labels can also add more security and reliability to your tape system. 
Section 8.4 describes why you would use tape labels, and also how to 
set up your system to begin labeling tapes. 

There are no dependencies among file archiving, file migration, and 
tape labeling. For example, you can use the file archiving facility 
without using file migration or tape labeling. Each tape facility can 
be used separately. There is, however, the dependency that tape drive 
allocation must be turned on to use tape labels. 



8.1 FILE ARCHIVING 

File archiving provides a means of storing data on magnetic tape and 
freeing valuable disk space. This type of off-line storage allows 
users to store (archive) important files on tape, keeping their disk 
space below their permanent allocation, and still have easy access to 
those files. 

If your installation has more than one computer system, the archive 
tapes can be common to all systems. You can put files on tape from 
one system, move a directory and its files to another system, and 
still retrieve files from the tape in the ordinary manner. 

Unlike general system backup tapes, the tapes that contain archived 
files are usually kept for a much longer time, for example, seven to 
ten years. 



8.1.1 Setting Up the System to Use File Archiving 

When you receive the TOPS-20 Installation Tape and have brought up the 
TOPS-20 monitor, your system contains a built-in default of 3650 days 
for recycling archived tapes. To change the 3650 day (10 year) 
default, you can enter a command in the n-CONFIG.CMD file. The 
command you use is: 

ARCHIVE-TAPE-RECYCLE-PERIOD days 

Select a length of time that is appropriate for your installation. 
Place the ARCHIVE-TAPE-RECYCLE-PERIOD command in the n-CONFIG.CMD file 
during software installation, or edit the file at a later date when 
you are planning to reload the system. 
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Each time the DUMPER program copies an archived file to tape, it 
places the expiration date argument in the FDB of the file. The MAIL 
program notifies users when a file on tape has reached its expiration 
date. If the file is no longer needed, the user can discard (using 
the DISCARD command) the information in the file's FDB that points to 
the file on tape. After all the files on a tape have passed their 
expiration dates and no users have FDBs in their directories that 
point to that tape, the tape can be recycled. Refer to Section 8.2.5 
for additional information on how to recycle tapes. 



8.1.2 What Happens When Users Archive Files 

Users archive files voluntarily by giving the ARCHIVE command. After 
a specific generation of a file has been archived (e.g., 
MYFILE.CBL.6) , it cannot change. Users can obtain copies of archived 
files by using the RETRIEVE command, but cannot alter those files. 
The TOPS-2 User' s Guide describes the ARCHIVE and RETRIEVE commands. 

When you establish your installation's policy for file archiving and 
notify users of its availability, you may want to instruct users to 
archive source files only. For example, files with a file type 

.CBL, .MAC, .TXT, .RNO, or .FOR 

should be archived; but, files with the file type 

.REL, .EXE, or .MEM 

should not be. This restriction saves space on your magnetic tapes. 

To completely archive a file, two copies must exist in the archives. 
This means that each archived file is stored on two tapes. Having the 
archived file on two tapes provides you with a backup tape if later 
you cannot retrieve a file off one of the tapes. The DUMPER program, 
which is used to archive files, records both tape identifying numbers 
in the FDBs of the files being archived. 



The diagrams below illustrate what happens 
file. 



when a user archives a 



First, the user creates a file. The File Descriptor Block (FDB), 
among other file information, contains a pointer to the location of 
the file on the disk. 




Pointer to File 



on the Disk 
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The user gives the ARCHIVE command for this file. The first or next 
time the operator runs DUMPER with the ARCHIVE command, the system 
locates all files that have been marked for archival by the ARCHIVE 
command and copies these files to tape. The FDB now contains pointers 
to the file on the disk and to the file on the tape. 




Pointer to File on the Disk 



Pointer to File on Tape 





MR-S-55S-80 



The second or subsequent time the operator runs DUMPER with the 
ARCHIVE command (remember that archived files are contained on two 
tapes), DUMPER copies the file again to the second tape. DUMPER then 
deletes the pointer to the location of the file on the disk. DUMPER 
places another pointer in the file's FDB to the second tape that 
contains the file and deletes the contents of the file on disk. After 
a user archives a file, the file name no longer appears in the user's 
directory list. The user must give the DIRECTORY command with the 
ARCHIVE or INVISIBLE subcommand to see the file name. 




Two Pointers to Tape 




MA-S-55&-B0 



8.1.3 What Happens When Users Retrieve Files 

Users request files be returned to disk (retrieved) by using the 
RETRIEVE command. When the operator runs DUMPER to process retrieval 
requests, DUMPER notifies the operator of the second tape that 
contains the file. If the file cannot be copied from the tape (e.g., 
the tape is bad) , DUMPER notifies the operator of the first tape that 
contains the file. When DUMPER returns a file to disk, the FDB of 
that file now contains two pointers to tape and one to the disk. The 
pointer to the file on the disk remains in the FDB until the file is 
deleted from disk. 



8.1.4 When to Create Archive Tapes 

You can select how often the operator runs DUMPER to archive files. 
However, running DUMPER (with the ARCHIVE command) every day before or 
after your general system backup procedure is probably closest to your 
present schedule. 
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The steps below provide an example of a typical procedure. These 
steps assume that this is the first time you are archiving files. The 
diagrams that accompany the steps show you what information is on the 
archive tape after each DUMPER operation. Although you do not have to 
use this procedure, it is one that best utilizes your tape resources. 
(The TOPS-20 Operator' s Guide describes the procedure for running 
DUMPER with the ARCHIVE command.) 



Step 



Procedure 



1. The operator runs DUMPER and performs the normal (incremental 
or full) backup procedures for the entire system. (Refer to 
Chapter 7, System Backup Procedures.) 

2. The operator mounts a brand new tape (a tape that has been 
initialized if you are using tape labels; refer to Section 
8.4.3) to contain the archived files, for example, TAPE 1. 




FIRST NIGHT 
NEW TAPE 



3. The operator runs DUMPER with the ARCHIVE command. DUMPER 
locates all files marked for archival and copies them to 
tape. 
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The next evening (or the next time system backup is 
performed), the operator mounts a brand new tape, e.g., TAPE 
2. He does NOT mount the tape used the first time. 




SECOND NIGHT 
NEW TAPE 



The operator runs DUMPER with the ARCHIVE command. This time 
DUMPER finishes the archival run of the previous night by 
making a second copy of those files. In addition, DUMPER 
locates all the files newly marked for archival and copies 
them to tape for the first time. 




6. The operator repeats this process every day until 
are full. 

7. For example, the third night, the operator mounts 
tape, TAPE 1. 



the tapes 



the first 



The operator runs DUMPER. DUMPER finishes the archival run 
of the previous night by making a second copy of the previous 
night's files. It also locates all the files newly marked 
for archival and copies them to tape. 



WRITTEN 
FIRST NIGHT 
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9. The fourth night, the operator mounts the second tape, TAPE 
2. Again, DUMPER finishes the archival run of the previous 
night by making a second copy of those files. It also 
locates all the files newly marked for archival and copies 
them to tape. 




NEWLY 


SECOND 


ARCHIVED 


COPY 


FILES 





MR-S-564-80 



NOTE 

DUMPER checks tapes for duplicate files. It does not 
write both copies of the same file on the same tape. 
If the wrong tape is mounted, DUMPER outputs an error 
message. 



8.1.5 Processing Retrieval Requests 

When a user gives the RETRIEVE command to request an archived file, 
the request is stored in a queue. You must establish a policy for how 
often the operator should process the retrieval requests contained in 
the queue. (The TOPS-20 Operator' s Guide describes how to process 
retrieval requests.) If you have encouraged users to archive their 
files, you should instruct the operator to process the request queue 
frequently. 



8.2 FILE MIGRATION 

Some installations must control the use of disk space by periodically 
migrating files to magnetic tape. This forced file migration allows 
the management of an installation to move old unused disk files to a 
less expensive storage medium. Similar to archived files, migrated 
files are still easily accessible to the user. File migration also 
allows you to keep users' directories below their permanent 
allocation. (Refer to Section 5.5 for a description of permanent and 
working storage allocations.) 

Whether you use the file migration facility depends almost entirely on 
your disk space resources. If users are archiving files regularly, if 
their directories are usually below their allowed permanent disk 
allocation, and your system is not continuously interrupted with "disk 
space low" messages, you may choose not to migrate files. Otherwise, 
if you are constantly receiving the [CAUTION - DISK SPACE LOW ON 
structure name] message, you may want to forcibly migrate files from 
the disk. 
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Sections 8.2.1 through 8.2.3 describe using file migration. They 
include: 

• the program you must run before migrating files to tape 

• the command that can be placed in the n-CONFIG.CMD file to 
change the default tape recycle period 

• when to run the REAPER program that marks file's for migration 
and marks for deletion the contents of archived and/or 
migrated files 

• a sample of the REAPER.CMD file that you can use as a default 
file to be read by the REAPER program 

• when to run the DUMPER program that locates files marked for 
migration and copies them to tape 

• when to process retrieval requests for migrated files 

• when to recycle migrated (and archived) tapes 



8.2.1 Setting Up the System to Use File Migration 

When you receive the TOPS-20 Installation Tape and have brought up the 

new TOPS-20 monitor, your system contains a built-in default of 180 

days for recycling migrated tapes. This default is placed in the FDB 
of each file as it is migrated to tape. 

To change the 180-day default, you can enter a command in the 
n-CONFIG.CMD file to inform the system when you plan to recycle your 
migrated tapes. This command is: 

TAPE-RECYCLE-PERIOD days 

Select a length of time that is appropriate for your installation. 
The default of 180 days, however, is a standard time period. You can 
place the TAPE-RECYCLE-PERIOD command in the n-CONFIG.CMD file at the 
time you install the system (refer to the TOPS-20 KL Model B 
Installation Guide ) . Or, you can edit the n-CONFIG.CMD TTle at a 
later date. Remember that if you edit the file at a later date, you 
must reload the system to process the commands in the n-CONFIG.CMD 
file. 

CAUTION 

If you decide to change the 180 day default, place the 
TAPE-RECYCLE-PERIOD command with the new argument in 
the n-CONFIG.CMD file and reload the system. 
Otherwise, the default recycling period does not 
change until the next system reload. 
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8.2.2 Using the REAPER Program 

The REAPER program is the tool used to free disk space. It performs 
the following functions: 

• Marks for migration the files that have not been referenced 
for a specified period of time 

• Marks for deletion the disk contents of archived or migrated 
files, either after they have been successfully copied to 
tape, or after they have been returned to disk with the 
RETRIEVE command, and have not been referenced for a 
specified period of time 

• Trims directories that are over permanent disk allocation by 
marking files in those directories for migration 

• Deletes (purges) the tape pointers in FDBs on the disk that 
have reached their tape storage expiration date. That is, 
the file's FDB will no longer contain a pointer to the 
contents of the file on tape. 

You can instruct the operator to run the REAPER program and perform 
one, several, or all of these functions. The operator can give a list 
of commands to REAPER or use the TAKE command with the default 
argument SYSTEM:REAPER.CMD. After the system is installed, the 
directory <SYSTEM> contains a default REAPER.CMD file. You can use 
this file as it is or use an editor and change the default parameters. 
The default SYSTEM: REAPER.CMD file appears similar to the following. 

♦TYPE (FILENAME) SYSTEM ! REAPER ,CMD<RET> 

! Sample REAPER policy file 

! Directories not to be considered (specify the structure snd directory) 

skip pub:<neu-subsys>.pub!<neu-system>»pub:<syste:m>.pub:<subsys> 

PERIOD 60 Ispecifies the age limit on 

•files 

MIGRATE 1 Files older than PERIOD days 

DELETE-CONTENTS I Of unreferenced files older than 

1PERI0D with tape backup 

TRIM IDirectories over perm allocation 

lback to perm allocation 

ORDER *.TMP,*.LST,*.REL !The order to take files during TRIM 

Note that the SKIP command includes a list of directories that are not 
to be touched by the REAPER program. You can add other system or user 
directories to this list. The list can contain approximately 75 
directories. Be sure that the operator always includes this command 
when running the REAPER program; otherwise, you may accidentally 
migrate some very important files from the disk. You can use more 
than one SKIP command to specify additional directories to be skipped, 
rather than list them all in one command. That way, if there is an 
error in processing one command, it will not affect the processing of 
the other commands. This is especially useful when SKIP commands are 
included in a file. 
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The REAPER program accepts the following commands. 

BEGIN (Processing files) 

DELETE-CONTENTS (Of old offline files) 

EXIT (To monitor) 

LIST (Output to file) 

MIGRATE (Old files to offline storage) 

ORDER (For trimming) 

PERIOD (For migration) 

PURGE (Expired FDBs from disk) 

SCAN (Only) 

SKIP (Directories) 

TAKE (Commands from file) 

TAPE (Check of tapes in use) 

TRIM (Directories over allocation) 

The TOPS-20 Operator' s Guide provides a complete description of all 
the commands that can be given to the REAPER program or placed in the 
REAPER.CMD file. Typically, you give a number of commands to REAPER, 
one for each operation you want performed. 

The availability of disk space determines how often you run the REAPER 
program. If your disk space is low, you may want to run the REAPER 
program daily to free up as much disk space as possible. Other 
installations may run it once a month or less. 



8.2.3 Using the DUMPER Program 

After the REAPER program marks files for migration, the operator runs 
the DUMPER program to copy the files to tape. Similar to an archived 
file, a migrated file is not completely migrated until two copies of 
the file exist on magnetic tape. Section 8.1.4 describes a procedure 
for copying archived files to tape. You can use this same procedure 
for migrated files, by using the MIGRATE command instead of ARCHIVE. 

If you use both the file archiving facility and the file migration 
facility, do not merge archived and migrated files on| the same tapes. 
The expiration dates for migrated files differ greatly from the 
expiration dates on archived files. If you put them on the same tape, 
you will end up saving migrated files for approximately ten years and 
use up all your tape resources very quickly. 



8.2.4 Processing Retrieval Requests for Migrated Files 

When a user gives a DIRECTORY command, the files that have been 
migrated to tape still appear in the directory list; however, each 
file has a notation (/OFFLINE) beside the filename to indicate that 
the file is contained on tape and not on the disk. The versions of 
migrated files that have been copied to tape can be returned to disk, 
and unlike archived files, they can be altered and/or renamed in the 
ordinary manner. The user requests that a migrated file be returned 
to disk with the RETRIEVE command. These requests are stored in the 
same queue as archive requests until the operator processes the queue. 
The TOPS-20 Operator' s Guide describes how to process retrieval 
requests. Retrieval requests for migrated or archived files should be 
processed frequently. 
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8.2.5 Recycling Migration (and Archive) Tapes 

When all the migrated or archived files on a tape have passed their 
expiration dates and all pointers to these files on the disk have been 
deleted, you can recycle the tape. 

The PURGE command to REAPER checks tape expiration dates and notifies 
users by the MAIL program when migrated or archived files on tape are 
about to expire. Users can retrieve the file to disk again or discard 
the tape pointer on disk if they no longer need the file. 

The operator can determine if a tape can be recycled by giving the 
TAPE command to REAPER. If a tape is not mentioned in the TAPE output 
list, this means that none of the disk structures that are on-line at 
this time and specified to REAPER contain FDB pointers to that tape. 
However, be sure that you check all possible places for on-line (disk) 
pointers to this tape. That is, run REAPER with the TAPE command on 
all the disk structures on all systems that may contain pointers to 
this tape. If files have passed their expiration date and pointers to 
them still exist on the disk, the operator can run REAPER with the 
PURGE command to delete these pointers. The operator should be 
certain that files are no longer needed before using the PURGE 
command. 

HINT 

When a migration tape is full, have the operator use 
the PRINT command to DUMPER to obtain a hard-copy 
listing of the tape contents. 



8.3 TAPE DRIVE ALLOCATION 

Tape drive allocation provides the system, and not the user, with 
complete control over tape drive usage. When accessing a magnetic 
tape, the user must give a MOUNT command to request that the operator 
mount the tape on a drive. Once the operator responds to the user's 
request, the user can access the tape. When the user is finished with 
the tape, the user gives the DISMOUNT command to release the tape 
drive back to the system. From the user's point of view, the MOUNT 
and DISMOUNT commands replace the ASSIGN and DEASSIGN commands. The 
operator selects the drive for the user, and the system informs the 
user how to access the tape. Using tape labeling requires that you 
use tape drive allocation; however, this does not restrict you to the 
use of labeled tapes only. 



8.3.1 When to Use Tape Drive Allocation 

Table 8-1 lists the differences between using and not using tape drive 
allocation. 
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Table 8-1: Tape Drive Allocation 



Tape Drive Allocation 


No Tape Drive Allocation 


You must make an entry in 
the n- CONFIG.CMD file to 
use tape drive allocation. 

Users can use labeled and 
unlabeled tapes. 

Users cannot give the 
ASSIGN and DEASSIGN 
commands for allocated tape 
drives, but must give the 
MOUNT and DISMOUNT 
commands. 

The operator should not use 
the UNLOAD button on tape 
drives, but should use the 
DISMOUNT command to OPR. 


No entry required in the 
n-CONFIG.CMD file. 

No support for labeled' tapes. This 
means that all tapes, whether they 
contain labels or not, are treated 
as unlabeled. 

Users can give the ASSIGN and 
DEASSIGN commands for allocated tape 
drives and cannot use the MOUNT and 
DISMOUNT commands. 

The operator may unload tapes using 
the UNLOAD button on the tape drive. 



8.3.2 How to Enable/Disable Tape Drive Allocation 

To use tape drive allocation enter the command 

ENABLE TAPE-DRIVE ALLOCATION 

in the n-CONFIG.CMD file. 

You can disable tape drive allocation on a tape drive by using the SET 
TAPE-DRIVE MTAn: UNAVAILABLE command. 



8.3.3 Tape Mounting Policy 

Occasionally, you may mount a tape that the system cannot read. For 

example, the operator mounts a tape that has a density of 800 bits per 

inch (bits/in) on a drive that does not support this density. The 

system checks tapes for labels; even if this tape contains labels, the 
incorrect density prevents the system from recognizing them. 

With such errors, the system can be set up to immediately unload the 
tape and protect it from being accidentally erased, or it can treat 
the tape as unlabeled and continue processing. 

If you do not want the system to classify these tapes, as unlabeled, 
you can place the TAPE-RECOGNITION-ERRORS command in the n-CONFIG.CMD 
file with the appropriate argument. The format of this command 
follows: 



TAPE-RECOGNITION-ERRORS 



REGARD-AS-UNLABELED 
UNLOAD 
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The system uses REGARD-AS-UNLABELED if no entry is made in the 
I n-CONFIG.CMD file. If REGARD-AS-UNLABELED is in effect, you should 
I instruct operators to be especially careful when mounting tapes with 
I write rings. The tape's contents cannot be overwritten if the write 
I ring is not inserted. 



8.4 TAPE LABELING 

This section describes what tape labels are and how, as system 
manager, you can initiate using them. 

Magnetic tape labels are records that are interspersed with 

user-defined data on a tape. They are informational records that 

describe the user data in a standard fashion that is recognized by 
many computer systems. 

The TOPS-20 tape labeling system allows you to read and write tape 
labels that conform to ANSI (American National Standards Institute) 
and DEC standards. The tape labeling system also allows you to read 
tapes that are labeled according to IBM labeling standards. 

Tape labeling is an option. You can start or continue to run your 
system using unlabeled tapes. If you have hundreds of unlabeled tapes 
at your installation, you may decide not to convert entirely to a 
labeled shop. Instead, you may have a combination of labeled and 
unlabeled tapes. 

Sections 8.4.1 through 8.4.3 describe the advantages of using tape 
labels and how to set up your system to begin labeling tapes. The 
TOPS-20 Tape Processing manual provides a complete description of the 
ANSI, DEC, and IBM standard label formats and how to use them. It 
also describes the interface between the operator and magnetic tapes 
and the user and magnetic tapes. 



8.4.1 Why Tape Labels? 

An unlabeled tape has a gummed label on the outside of the reel that 
identifies the contents of the tape. When the operator selects, 
mounts, and types the identity of an unlabeled tape, the system 
assumes that the mounted tape is the one that the user (or job) 
requested. No checking is performed by the system. 

A labeled tape, however, contains standardized information on the tape 
itself that identifies and describes the data on the tape. This 
internal label information is in addition to the gummed label on the 
outside of the reel. With labeled tapes, the operator selects a tape 
(by looking at the outside gummed label) , mounts the tape on any 
available drive, but does not type in any identifying information at 
the terminal. When a user issues a MOUNT request for a labeled tape 
that is already mounted, the system automatically locates the drive 
containing the tape requested, and checks to ensure that the correct 
tape has been mounted. This facility for automatically locating and 
checking tapes is described further below. 
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A labeled tape consists of a volume label group, followed by one or 
more files. (A volume is a reel of magnetic tape.)' The volume label 
group is a set of one or more records at the beginning of the tape. 
It contains a volume identifier, commonly referred to as a VOLID, and 
other identifying information. (See Figure 8-1.) You, as system 
manager, select the VOLIDs to be used at your installation. The VOLID 
is a name containing from one to six alphanumeric characters. A user 
requests access to a specific volume by specifying! its VOLID to the 
system. 

Each file on a labeled tape contains a file header label group, the 
file data (written by the user program) , and a fiile trailer label 
group. (See Figure 8-1). Optionally, the file can contain user 
labels, whose contents are specified and examined only by user 
programs. Volume labels, header labels, trailer labels, and user 
labels are described in the TOPS-20 Tape Processing manual. 
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Figure 8-1: Organization of Labeled Tapes 



Because every labeled tape contains a unique identifier, or VOLID, the 
system can read this VOLID and ensure that the correct tape has been 
mounted. This automatic checking improves the reliability of your 
tape system. It significantly reduces the likelihood of an operator 
mounting the wrong tape. 
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• The operator does not have to type tape- identifying 
information to the system when mounting a labeled tape. 

• It provides a faster connection between a user's job and the 
tape requested. 

• The operator can mount a tape long before it is needed. When 
a job requests the tape, the system locates the drive that 
contains the requested tape and readies it for use. 

Tape labels also improve the security of yourj tape system. 
DEC-standard labels identify the owner, as well as tjie volume, in the 
volume label. The file labels specify protection: codes for the 
individual files. These labels protect a tape from being 
inadvertently written on and valuable data destroyed by a user who 
does not have the appropriate access rights to the tape or its files. 
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In addition to the added reliability, security, and volume 

recognition, labeled tapes provide you with a means of interchanging 

tapes between DECSYSTEM-20S and other computers. This interchange 

capability extends the mobility of data between different systems. 

You can write ANSI" and DEC-standard labeled tapes and mount these 

tapes on other systems using ANSI- or DEC-standard labels, and vice 

I versa. You can mount a labeled tape that was written in EBCDIC with 

I labels conforming to IBM's OS standards, and read it on a DECSYSTEM-20 

I as if it were ANSI-standard labeled. 

Finally, if you are using the TOPS-20 tape drive allocation facility, 
you can charge users for their tape usage. Note that you must use 
tape drive allocation with labeled tapes, but you can use it with 
unlabeled tapes also. The accounting usage file contains entries for 
all tape-mount requests. The TOPS-20 USAGE File Specification 
describes the formats of these entries and how they are used in 
reports and billing. 



8.4.2 Setting Up the System to Use Tape Labels 

To use tape labels, you must have at least one tape drive that is 
9-track and has the capability of using tapes at a density of 800, 
1600, or 6250 bits per inch (bits/in) . There is no restriction on the 
number of these drives you use. The TOPS-20 Tape Labeling system can 
be used with as many drives as are allowed for your system. 

Also, you must enter the ENABLE TAPE-DRIVE-ALLOCATION command in the 
n-CONFIG.CMD file. The TOPS-20 KL Model B Installation Guide 
describes the format of this command and how to enter it into the 
n-CONFIG.CMD file at the time you install the system. If you do not 
enter this command during software installation, you can edit the 
n-CONFIG.CMD file at a later date. However, if you edit the file at a 
later date, you must shut the system down and bring it back up again 
to process the commands in the n-CONFIG.CMD file. 



8.4.3 Initializing Tapes and Drives to Use Labels 

Tapes must be initialized before they can contain labels. An 
initialized tape contains a volume label set followed by an empty 
file. The operator issues commands to OPR to initialize tapes for use 
by the TOPS-20 Tape Labeling system. All the necessary volume labels 
are then created on a tape. (Refer to the TOPS-20 Operator's Guide 
for a description of using OPR to initialize tapes.) 

You should initialize as many scratch tapes as you will need to store 
your system's data before users start issuing MOUNT requests for 
tapes. Then, when a user issues a MOUNT command without specifying a 
VOLID, the operator mounts an initialized scratch tape of the 
appropriate label type. TOPS-20 then readies (loads) the tape for 
write access by the user program. 



8-15 



TAPE STORAGE 



In addition to initializing tapes, you can set some or all of your 
tape drives to use the automatic volume recognition facility (AVR) . 
As described earlier, AVR sets your tape drives to automatically 
recognize tape volumes as they are mounted. To turn on automatic 
volume recognition, have the operator enter the following command in 
the <SYSTEM>SYSTEM.CMD file: 

ENABLE AUTOMATIC-VOLUME-RECOGNITION (FOR) object 

Where object is either TAPE-DRIVE MTAn: or TAPE-DRIVES. 

You can turn off AVR by entering the following command in the 
<SYSTEM>SYSTEM.CMD file: 

DISABLE AUTOMATIC-VOLUME-RECOGNITION (FOR) object 

These commands can be given to OPR at any time to enable or disable 
AVR for any or all drives on the system. 

It is generally a good practice to enable AVR for all drives. 



8.5 SHARING TAPE DRIVES BETWEEN TWO SYSTEMS 

If you have two DECSYSTEM-20S , you can set up the systems to share a 
TX02 tape subsystem by use of the TX03 option, as Figure 8-2 shows: 



DECSYSTEM 20 



DECSYSTEM-20 



DX20 



Standard Single Channel 




TX02 



- TX03 Dual-Channel Option 




-Tape Drives 



MR-S-3918-85 



Figure 8-2: TX02 Tape Subsystem 



Note, however, that use of the drives must be under i strict operator 
control. Without this control, it is likely that two users, on 
different systems, will eventually end up using the same tape. 
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Operator control is required because: 

• Unlike disk drives, there is no mechanism to control the 
porting of a tape drive between systems. If the tape drive 
is available to the TX02, then it is available to any system 
to which the TX02 is connected. 

• Furthermore, the MOUNTR programs on the two systems do not 
communicate, so they cannot, coordinate access to the drives. 
Thus, the MOUNTRs on the two systems would allow two users 
access to the same physical tape drive. 

Operator P rocedures 

1. All drives that are not to be used by a particular system 
should be set unavailable to MOUNTR with the OPR command: 

OPR> SET TAPE-DRIVE MTAx : UNAVAILABLE 

This command takes away control of the tape drive from MOUNTR 
and writes an entry in the DEVICE-STATUS.BIN file. During 
system reloads, MOUNTR reads this file, and if a tape drive 
has been set unavailable, will never try to access or assign 
the drive. Note that if DEVICE-STATUS.BIN is ever damaged, 
then a new file is created at system startup. However, all 
data and settings will have been lost, including data for the 
drives that have been set unavailable. Therefore, the 
operator will need to repeat this step. 

2. Setting the drive unavailable to MOUNTR does not prevent a 
user from reserving the drive with the ASSIGN command. To 
prevent a user from assigning a tape that is set unavailable 
to MOUNTR, a program under control of the operator should 
assign to itself all of the "unavailable" drives. This 
program should be run at system startup, before any users are 
allowed to log in. 

You could also control the assignment of tape drives with an 
access control program. Refer to Section 11.1, Access 
Control Program. 

An example of re-porting a tape drive from system A to system B 
follows. The operator: 

1. Removes the tape (if any) from the tape drive that is to be 
ported over to system B. 

2. Sets the drive unavailable to MOUNTR on system A. 

( OPR> SET TAPE-DRIVE MTAx: UNAVAILABLE ) 

3. Assigns the drive to a process under control of the operator 
on system A. 

4. Deassigns the drive from the process that is under operator 
control on system B. 

5. Sets the drive available to MOUNTR on system B. 

( OPR> SET TAPE-DRIVE MTAx: AVAILABLE ) 
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CHAPTER 9 
SYSTEM PROBLEMS/CRASHES 



This chapter describes the actions to take when you are faced with 
various system problems. You may have to correct a problem with the 
file system, act immediately after a power failure, or remove the CI 
from system use. There may be times when you cannot trace a problem. 

nroa^l tim6S ' Digital Fi \ ld Service can remotely run diagnostic 
programs on your system. The following sections address these topics. 

fnof,K S th u fc require 4 V0U t0 correct a Problem in the file system seldom 
occur. However, if a problem of this nature arises, you can perform 

severe! a ?he S Ire- ^^ Corrections ' Fr ™ the least to mos? 

• Restore a single file in a directory 

• Restore a single directory (other than <ROOT-DIRECTORY>) 

• Restore <ROOT-DIRECTORY> 

• Restore the entire file system 

The TOPS -2 Operator's Guide provides all the necessary information 
™ n „? e Q 2 perat ?5 t0 correct these ^Pes of problems. Sections 9.1 
solved Provide you with an overview of how these problems are 



9.1 RESTORING A SINGLE FILE 

fol?owing eC proced a ureT eSt t0 ^^ * " le '« a USer ' y ° U Ca " USe the 

1. Look in the binder that contains the listing of the DUMPER 
log files. (Chapter 7 describes creating DUMPER log files.) 

2. Write down the file specification (including the structure 
and directory) to be restored, and the date and number of the 
tape containing the file. Be sure to indicate the 
destination structure and directory if one or both are 
different from the structure and directory from which the 
file was saved. 

3. Submit a request to the operator to restore the file. 
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9.2 RESTORING A SINGLE DIRECTORY 

If you receive a request to restore a directory, you can use the 
following procedure. 

1. Determine the structure that contains the directory. 

2. Make sure you have a copy of the files in this directory on a 
DUMPER tape. (Check the log files.) 

3 Give the "ECREATE command with the LIST subcommand . Write 
' down the list of parameters, for example, the directory 

nuSer, allocation, etc. You may need this information when 
you re-create the directory. 

4 Give the "ECREATE command with the KILL subcommand for the 
* directory. (The TOPS-20 Operator's Guide P™ ld " ad S|£2S£ 

procedures for delim^Ta single directory if the ECREATE 
command with the KILL subcommand is unsuccessful.) 

5. Using your DUMPER backup tapes, first restore the files from 
the last FULL-INCREMENTAL DUMPER operation. Then, restore 
files from each INCREMENTAL tape until the time when the 
files were lost. Be sure the operator gives the CREATE 
command to DUMPER to restore the directory parameters. 

If the directory contains unreproducible information and it is not 
backed up on tape, call Digital Software Services for assistance. It 
mS be possible to reconstruct the directory without losing the valid 
information in it. 



9.3 RESTORING <ROOT-DIRECTORY> 

Each structure has its own <ROOT-DIRECTORY> and a backup 
<ROOT-DIRECTORY> that is used by the system^ if the primary 
<rS-DIRECTORY> is bad. The directory <ROOT-DIRECtORY> contains a 
Sinter to each first-level directory on a structure, as well as 
KverTl important system files. . (Chapter 5 ."^Jjjj^ ^ 
<R00T-DIRECT0RY> points to directories.) If <ROOT-DIRECTORY> is lost 
on the public structure, users cannot access any files in the system. 
It <R00T-DIRECT0RY> is lost on a mountable structure, users cannot 
access files on that structure. 

You can tell that the <R00T-DIRECT0RY> on the public structure ^ bad 
if the operator's console prints any one of the BUGHLTs listed in 
Table 9-1. When a BUGHLT appears on the console, the system stops. A 
BUGHLT appears in the form: 

********** 

*BUGHLT name AT dd-mm-yy hh:mm:ss 

*J0B:n, USER: user-name 

♦ADDITIONAL DATA: data , data , data 

********** 

The lines beginning with JOB: or ADDITIONAL DATA: may not appear. 
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Table 9-1: <ROOT-DIRECTORY> BUGHLTS 



BUGHLT 


Meaning 


BADROT 
FILIRD 
FILMAP 

BADXT1 


<ROOT-DIRECTORY> is invalid 

The system could not initialize <ROOT-DIRECTORY> 

The system could not map <ROOT-DIRECTORY> into 
memory 

The index table is missing and cannot be created 



<ROOT-DIRECTORY> may also be bad if you get the BOOT error ?FIL NOT 
FND. If this error appears, be sure you have mounted all devices 
correctly. 

To recover from a bad <ROOT-DIRECTORY>, first determine which 
structure contains the bad directory. If the bad <ROOT-DIRECTORY> is 
on a mountable structure, you can run CHECKD with RECONSTRUCT 
ROOT-DIRECTORY and specify the proper structure. The TOPS-20 
Operator' s Guide details the procedure for determining the structure 
and using CHECKD for reconstructing <ROOT-DIRECTORY> on mountable 
structures. 

If the bad <ROOT--DIRECTORY> is on the public structure, you can 

instruct the system to use the backup public structure 

<ROOT-DIRECTORY> and rebuild this directory. Section 9.3.1 describes 
this procedure. 

NOTE 

If your first attempt to rebuild <ROOT-DIRECTORY> 
fails, call your DIGITAL Field Service Representative. 
NEVER try to rebuild this directory twice on any 
structure. 



9.3.1 Rebuilding the Public Structure <ROOT-DIRECTORY> 

To rebuild <ROOT-DIRECTORY> on the public structure, halt the central 
processor and perform Steps 7 through 21 in Chapter 2 of the TOPS-20 
KL10 Mode l E_ Installation Guide. The steps are shown below for 
reference. 

1. Type CTRL/backslash on the operator's console; the system 
prints PAR>. 

2. Type SHUTDOWN and press the RETURN key; the system prints a 
few message lines. 

PAR>SHUTDOWN<RET> 
**HALTED** 

%DECSYSTEM-20 NOT RUNNING 
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3. Mount System Floppy A in drive (Step 7). 

4. Mount System Floppy B in drive 1 (Step 8). 

5. Mount the TOPS-20 Installation Tape on MTA0: (Step 9). 

If the TOPS-20 Installation Tape is not your most recent 
system backup tape, mount your SYSTEM BACKUP TAPE that 
contains the monitor, TOPS-20 Command Processor, DLUSER, 
DLUSER data, DUMPER, and save sets containing <SYSTEM> and 
<SUBSYS>. (Refer to Section 3.2 for a description of special 
system directories.) 

6. Place the front-end HALT switch in the ENABLE position (Step 
10) . 

7. Set the front-end switch register to 000007 (octal) (Step 
11). 

8. Press the ENABLE and SWITCH REGISTER switches simultaneously 
(Step 12) . 

RSX-20F VB15-21 8:55 l-JAN-85 

[SY0: REDIRECTED TO DX0:] 

[DX0: MOUNTED] 

[DX1: MOUNTED] 

KLI — VERSION VB15-15 RUNNING 

KLI — ENTER DIALOG [NO, YES, EXIT, BOOT] ? 

KLI> 

NOTE 

The version and edit numbers in this manual 
may differ from the numbers printed on your 
console. The numbers on your console must be 
equal to or greater than the numbers! in this 
manual. 

9. Type YES and press the RETURN key (Step 13). 

KLI>YES<RET> 

KLI — KL10 S/N: 2136., MODEL B, 60 HERTZ 

KLI — KL10 HARDWARE ENVIRONMENT 

MOS MASTER OSCILLATOR 

EXTENDED ADDRESSING 

INTERNAL CHANNELS 

CACHE 
KLI — RELOAD MICROCODE [YES , VERIFY, FIX, NO] ? 
KLI> 
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I 10. Type YES KLX and press the RETURN key (Step 14). 

I 

| KLIXYES KLX<RET> 

I KLI — MICROCODE VERSION 400 LOADED 

NOTE 

If your system has cache memory, the 
following question appears previous to the 
question in Step 11. (Step 15.) 

KLI — RECONFIGURE CACHE (FILE, ALL, YES , NO) ? 

Type ALL and press the RETURN key (Step 16) . 

KLI>ALL<RET> 

KLI — ALL CACHES ENABLED 

11. Type ALL and press the RETURN key (Step 17). 

KLI -- CONFIGURE KL MEMORY CFILE. ALU REVERSE ,F0RCE iYES»N03? 

KLI>ALL<RET> 

LOGICAL MEMORY CONFIGURATION 

CONTROLLER 
ADDRESS SIZE RQO RQ1 RQ2 R03 CONTYPE INT 
0O0O0OOO 256K 00 01 00 01 MB20 4 
KLI -- LOAD KL BOOTSTRAP [YES >N0 r FILENAME]? 
KLI> 

I 

I 12. Type MTBOOT and press the RETURN key (Steps 18 and 19). 

KLI>MTBOOT<RET> 

KLI — CONFIGURATION FILE ALTERED 

KLI — WRITE CONFIGURATION FILE [YES, NO]? 

KLI — NO 

BOOTSTRAP LOADED AND STARTED 

BOOT Vll. 0(306) 

MTBOOT > 

I 

I 13. Type /L and press the RETURN key (Step 20). 

MTBOOT> /L<RET> 

[BOOT: STARTING CHN:n DX20x:0 MICROCODE Vn(n)][OK] 

[BOOT: LOADING RESIDENT MONITOR] [OK] 
MTBOOT> 

NOTE 

I The message concerning the DX20 microcode is 

I printed only if you are installing the 

I TOPS-20 software on a DECSYSTEM-20 with a 

I DX20 tape or disk controller. 
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14. Type /G143 and press the RETURN key (Step 21). 

MTBOOT> /G143<RET> 

[FOR ADDITIONAL INFORMATION TYPE "?" TO ANY OF THE 

FOLLOWING QUESTIONS.] 

DO YOU WANT TO REPLACE THE FILE SYSTEM ON THE SYSTEM 

STRUCTURE? 

NOTE 

Read Step 15 carefully before answering this 
question. 

15. Type N and press the RETURN key. You DO NOT want to clear 
all the information on the disk packs. If you want to retain 
all the information in the file system, always type N. 

DO YOU WANT TO REPLACE THE FILE SYSTEM ON 
THE SYSTEM STRUCTURE? N<RET> 

[PS MOUNTED] 

[BOOT: LOADING SWAPPABLE MONITOR, PASS1] [OK] 

RECONSTRUCT ROOT-DIRECTORY? 

16. Type Y and press the RETURN key. This causes the backup copy 
of <ROOT-DIRECTORY> to be used. 

RECONSTRUCT ROOT-DIRECTORY? Y<RET> 

[RECONSTRUCTION PHASE 1 COMPLETED] 

%%NO SETSPD 

System restarting, wait... 
ENTER CURRENT DATE AND TIME: 

The system restarts and runs CHECKD to reconstruct the bit 
table. The bit table contains one bit for every page in the 
file system. If the bit is on, the page is available; if the 
bit is off, the page is in use. 

17. Type the date and time and press the RETURN key. Type Y and 
press the RETURN key to confirm the date and time. 

ENTER CURRENT DATE AND TIME: l-JAN-81 0931<RET> 

YOU HAVE ENTERED THURSDAY, 01-JANUARY-1981 9: 31AM, 
IS THIS CORRECT (Y,N) Y<RET> 
WHY RELOAD? 
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18. Type OTHER and press the RETURN key. 

WHY RELOAD? OTHER<RET> 
[REBUILDING BIT TABLE] 

NOTE 

You should type a response to WHY RELOAD?, 
that reminds you of why you did this 
procedure. This response is stored in the 
<SYSTEM-ERROR>ERROR.SYS file. Refer to the 
TOPS-20 KL10 Model B Installation Guide for a 
complete list of valid abbreviations. 

19. The system prints some standard messages, the output from 
CHECKD, RUNNING DDMP, and the output from SYSJOB and PTYCON. 

[REBUILDING BIT TABLE] 

[WORKING ON STRUCTURE - PS:] 

output from CHECKD 

RUNNING DDMP 

output from SYSJOB and PTYCON 

Refer to the TOPS-20 Operator' s Guide for samples of the 
output from CHECKD, SYSJOB and PTYCON. 

20. Log in as user OPERATOR. 

TOPS-20 SYSTEM, TOPS-20 Monitor 6.1(6701) 

@LOGIN (USER) OPERATOR (PASSWORD) (ACCOUNT) OPERATOR<RET> 

Job 1 On TTY1 3-MAY-85 10:33i32 



9.4 RESTORING THE ENTIRE FILE SYSTEM 

If you are still receiving random errors and cannot use the system, 
you may have to restore the entire file system on the public 
structure. Before doing this, you should contact your software 
specialist to ensure that resorting to this procedure is necessary. 
The procedure requires shutting down the system and reinstalling the 
file system. 



9.4.1 Re-creating the File System on the Public Structure 

The following steps outline the procedure for restoring the file 
system on the public structure. 

1. Type CTRL/backslash to start the front-end command parser. 

CTRL/backslash 

PAR> 
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2. Type SHUTDOWN to stop the central processor; the system 
prints a few messages. 

PAR>SHUTDOWN<RET> 
**HALTED** 

%DECSYSTEM-20 NOT RUNNING 

3. Start at Step 9 in Chapter 2 of the TOPS-20 KL Model B 
Installation Guide and follow all the steps through Step 60. 

In Step 9, instead of mounting the TOPS-20 Installation Tape, 
mount your public structure SYSTEM BACKUP TAPE that contains 
the monitor, TOPS-20 Command Processor, DLUSER, DLUSER data, 
DUMPER, and save sets containing <SYSTEM> and <SUBSYS>. 

4. After performing Step 60, restore your entire file system 
using DUMPER. First run DUMPER, then mount: your first reel 
of the most recent full DUMPER tape and follow the procedures 
in the TOPS-20 Operator's Guide . 

5. Re-create the front-end file system by following the 
directions in Chapter 4 of the TOPS-20 KL Model B 
Installation Guide . 

6. Finally, restart the system by following thej directions in 
Chapter 5 of the TOPS-20 KL Model B Installation Guide . 

NOTE 

Restore the incremental saves to obtain the most 
recently saved files. Before restoring each 
incremental tape, type DUMPER>CREATE to restore all 
the directories that were created since the last time 
you ran the DLUSER program. 



9.4.2 Re-creating Mountable Structures 

If, after your efforts to correct errors on a structure other than the 
public structure (using the command RECONSTRUCT ROOT-DIRECTORY to 
CHECKD) , you still cannot use the structure, you can re-create that 
structure and restore all the directories and files. You can restore 
structures other than the public structure during timesharing. 

To restore a mountable structure you must: 

1. Give the SET STRUCTURE IGNORED command to the OPR program to 
prevent other users from mounting the structure while you are 
re-creating it. 

2. Run CHECKD to create the structure. 

3. Run DLUSER to restore directory parameters for the structure 
if you previously used the program to save the parameters. 

4. Run DUMPER using the backup tapes for this structure. Give 
the CREATE and RESTORE commands to DUMPER to restore all the 
directories and files. 

The TOPS-2 Operator' s Guide details the procedures for running CHECKD 
and DUMPER to re-create a structure. 
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9.5 POWER FAILURES 



Unfortunately, power failures and brown-outs sometimes occur at 
installations. You should be aware of the immediate steps to perform 
and transmit this information to your operations people. The kind of 
attention you should direct to this type of problem depends on the 
type of outage you have. These steps can protect your system from 
physical damage and perhaps unnecessary loss of files. 

If your system experiences a total power failure, you should: 

1. Immediately power-off all components of the system. 

2. Inform your DIGITAL Field Service representative as to when 
you expect to resume power. The field service representative 
may ask to be present while you bring your system back up. 

If your system experiences a short instance of a power failure or 
brown-out, the system may recover on its own. You may not have any 
problems and, usually, all your data remains intact. If you notice a 
problem, call your Field Service representative. 

High-performance computer systems are sensitive to the quality of the 
electrical power supply. An investment in a power conditioner or an 
uninterruptible power supply may more than repay itself in improved 
system reliability and availability. Your Field Service 
representative may be able to assist you in evaluating the need for 
such equipment. 



9.6 REMOTE DIAGNOSTIC LINK (KLINIK) 

You may occasionally have a problem with your system and cannot 
determine the cause. The remote diagnostic link, available on all 
systems, allows a DIGITAL Field Service engineer to access your system 
from a remote location and run diagnostic programs. This capability 
is called KLINIK. The DIGITAL engineer accesses KLINIK through a 
terminal and telephone line at the DIGITAL Service Center. The 
TOPS-20 Operator' s Guide describes when and how to use the KLINIK 
capability. 



9.7 MAKING THE CI UNAVAILABLE ON NON-CFS SYSTEMS 

The CI, a computer-interconnect bus, is a key piece of hardware for 
connecting systems in a CFS-20 configuration and for connecting 
HSC50-based disks (RA81s and RA60s) to a system. Ordinarily, you need 
do nothing at all to operate the CI. However, you may need to 
disengage a system from the CI so Field Service personnel can correct 
problems with the CI20 or the HSC50. At those times, you should 
instruct the operator to make the CI unavailable by means of the SET 
PORT CI UNAVAILABLE command. (Refer to the TOPS-20 Operator's Guide 
for details.) 

When the CI is unavailable to a system, users cannot access 
HSC50-based disks, which rely on the CI to transmit data. The 
procedure calls for the operator to dismount any structures that the 
system indicates are mounted on these disk drives. 

To put the CI back in operation, the operator gives the command: 

OPR>SET PORT CI AVAILABLE 
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Structures that were affected must then be remounted. 

Refer to Chapter 12, THE COMMON FILE SYSTEM, for information on 
disengaging the CI on CFS systems. 



9.8 MAKING THE NI UNAVAILABLE 

A system may need to be disengaged from the NI so that field service 
personnel can diagnose problems with the NI or the NIA20. To make the 
NI unavailable to a system, the operator gives the command: 

OPR>SET PORT NI UNAVAILABLE 

This command prevents users of the system from using LAT terminal 
servers as well as any other software that uses the NI. If DECnet or 
TCP/IP software is installed, it cannot use the NI for data transfer 
between systems. To make the NI available again, the operator gives 
the command: 

OPR>SET PORT NI AVAILABLE 
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CHAPTER 10 
SYSTEM PERFORMANCE 



The configurations of systems running TOPS-20 and the mix of jobs on 
these systems vary from installation to installation. TOPS-20 is 
designed to provide better response to interactive users than to 
provide higher throughput to computational tasks. On systems with a 
typical mix of interactive and batch jobs, this design provides both 
good response and adequate throughput. Therefore, if your system has 
many timesharing users and an average amount of batch processing jobs, 
you will find that your system's response is good and most users are 
satisfied. 

If you have a mix of jobs or a configuration different from a typical 
system, you may want to change the response of your system to provide 
better service to specific users. TOPS-20 provides several tuning 
mechanisms that allow you to experiment with and change the behavior 
of your system. One mechanism allows you to favor classes of users by 
allocating each class a specified percentage of the CPU. Another 
mechanism allows you to favor computational jobs over interactive 
jobs. A third mechanism allows you to disable features that normally 
provide better performance, but that may not be applicable at your 
installation. 

This chapter describes the mechanisms for tuning your system's 
response and provides guidelines for using these mechanisms. Because 
the response of your system can be felt during actual use only, you 
can expect system tuning to be an experimental and iterative process. 
By analyzing the statistics from the WATCH program and by gathering 
inputs from your users, you can determine the best way to tune your 
system. 

The tuning mechanisms include: 

• The class scheduler, which allows you to divide the central 
processor (CPU) resource among groups of users 

• Assigning low priority to batch jobs for installations that 
do not use the class scheduler 

• Bias control, which allows you to favor either interactive or 
compute-bound jobs on your system 

• The program name cache for improving the startup time of 
frequently used programs 

• Reinitializing disk packs in heavily used structures for 
improving file processing time 

Each mechanism can be used independently. Unless otherwise noted, 
there is no interrelationship among them. 
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10.1 THE CLASS SCHEDULER 

Occasionally, certain jobs monopolize the central processor's time 
while other more critical jobs wait for the CPU. You may want to 
control the amount of CPU time a job receives. You can use the class 
scheduler to provide an even distribution of CPU time or to provide 
more CPU time to critical jobs on the system. Some system managers 
may want to allocate a larger amount of processor time to special 
users than to other system users. Sections 10.1.1 through 10.1.9 
describe: 

• an overview of the class scheduler 

• who should use the class scheduler 

• how to begin using the class scheduler 

• turning on the class scheduler 

• changing class percentages 

• disabling the class scheduler 

• getting information about class scheduler status 

• a sample session using class scheduler commands 

• an alternative to using the class scheduler with accounts. 



10.1.1 Overview 

The class scheduler allows you to allocate percentages of the central 
processor's time to individual classes of users. Each job in a class 
receives a portion of the class percentage. Therefore, by using the 
class scheduler, you can provide a consistent service to predefined 
groups of users. 

The diagram below illustrates the concept of classes and percentages 
of CPU time allocated to each class. Note that you can set up a class 
to include all batch jobs. This allows you to control batch jobs 
separately from timesharing jobs. The batch class is given a high 
percentage or a low percentage. Now, each time a user submits a batch 
job, the scheduler uses the batch class and not the user's class. 
Section 10.1.4, Step 5, describes how to create a batch class. 



CLASS 



CLASS 3 




CLASS 1 



CLASS 2 
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You can define class memberships by using the TOPS-20 accounting 
facility or by writing your own access control program. Section 
10.1.9 provides an overview of using an access control program to 
define classes. The following description applies to using the class 
scheduler with the accounting facility. 

Using the accounting facility, you can associate a class number with 

each account on the system. Each account has only one class 

associated with it„ Therefore, only a user who has access to more 
than one account can have access to more than one class. The user 

changes classes by changing accounts. To use this method, you must 

enable account validation so that users are required to use a valid 
account. Section 10.1.4 describes the accounting file entries. 

The scheduler periodically computes the time used by classes and 
individual jobs within a class. The scheduler's first concern is that 
a class receive its share of the CPU time. The scheduler gives a 
greater percentage of time to the class that is the farthest away from 
its target (the total percentage allocated to the class) . The 
scheduler's second concern is that each job within a class receive its 
fair share. Periodically, the scheduler computes the average amount 
of CPU time that a job has accrued. This quantity determines the 
job's priority within the class. A job that is requesting the CPU and 
is farthest way from receiving its fair share within the class 
receives a greater percentage of time within that class. 

Generally, the CPU has unused time. This unused time is called 
windfall. Windfall occurs if one or more classes has no logged-in 
jobs, or if one or more classes has an insufficient demand for the CPU 
to use all of its class percentage. 

You can handle windfall in one of two ways: allocate it or withhold 
it. Allocating windfall means that the excess CPU time is awarded 
proportionately to the active classes, (In this discussion, the term 
active class refers to a class that has logged-in users requesting CPU 
time.) Higher percentage classes receive proportionately more of the 
available windfall than lower percentage classes. This means classes 
can receive slightly more than their allowed percentages when there is 
windfall available. Note that windfall is distributed proportionately 
to each class and not to each job within a class. 

Withholding windfall means that the excess CPU time is idle time and 
it is not distributed to the active classes. It also means that 
classes do not receive more than the percentage allowed for them. 
Usually, it is better to allocate windfall, and not withhold it so you 
don't throw away valuable computer time. 



10-3 



SYSTEM PERFORMANCE 

10.1.2 Who Should Use the Class Scheduler? 

As mentioned earlier, the class scheduler allows you to divide the 
user community into defined classes and allocate a percentage of CPU 
time to each class. This intended use may not be beneficial or 
practical for some systems. Tradeoffs do exist and some installations 
do not require class scheduling. Therefore, read the following 
paragraphs and determine if your system needs this type of control. 
Several instances that can benefit from using the class scheduler are: 

• You can elect to sell portions of CPU time. For example, 
customer X can purchase some percentage of computer time at a 
proportional cost. You should, in this case, invite customer 
X to your installation and provide an environment that 
simulates the kind of response this customer can expect at 
this percentage. Because it is impossible to create the 
environment exactly as the customer will experience it at all 
times, customer X may decide later to change the purchase to 
a different percentage. 

• If you have a natural division among the users of the system, 
you can divide these users into classes, then distribute CPU 
time to these classes with respect to their importance on the 
system. For example, in an educational environment, you may 
have administrative users (doing payroll, grades, etc.), 
faculty users (perhaps working on a funded research project) , 
and student users (who are computer science majors) . Using 
the class scheduler, you can establish three classes and 
distribute the CPU time according to the importance or pay 
rate of each class. 

• If you wish to give preference to batch jobs, you can use the 
class scheduler to give the batch class a high percentage of 
the CPU. 

Conversely, you may not want to use the class scheduler for some of 
the following reasons: 

• If you have not realized a need in the past for class 
scheduling, or if you have a new system and do not see an 
immediate requirement for class scheduling, you should not 
set it up. 

• Systems with minimal amounts of memory may experience an 
increase in swapping. This additional overhead may offset 
any advantage gained by using the class scheduler. 

• In addition to other tasks, the scheduler constantly 
maintains usage values for each class and job. Because of 
this extra overhead, the overall system throughput decreases. 
Therefore, use the class scheduler if allocating percentages 
to individually defined classes outweighs the throughput 
depreciation. 

• To give batch jobs a low priority on the system, you do not 
have to use the class scheduler. Section 10.2 describes 
placing the BATCH-BACKGROUND command in the n-CONFIG.CMD file 
to place all batch jobs in a low priority (or background) 
queue. 
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10.1.3 How to Begin Using the Class Scheduler 

If you elect to use the class scheduler, first divide the system users 
into classes. Next, determine the amount of CPU time each class 
should receive. Percentages given to classes are typically in units 
of 5, that is, 5%, 10%, 15%, ...„100%. The sum of the percentages 
given to all classes cannot exceed 100 percent. The result of these 
two steps depends on the reason you elected to use the class 
scheduler, and how you plan to use it at your installation. Because 
of this system dependency, step-by-step procedures for selecting 
classes and allocating the CPU cannot be given. The following 
discussion provides you with guidelines for setting up the class 
scheduler to meet your system's needs. 

• Start with as few classes as possible, three or perhaps four. 
The class scheduler allows eight. Later, you can divide 
classes further, if necessary. 

• Determine the number of logged-in users you expect in each 
class. Be sure that you do not overload a class, making it 
impossible to give a sufficient percentage of the CPU to each 
job in the class. Also, you can limit the number of users in 
a class, but you cannot limit the number of jobs. For 
example, the SUBMIT command creates an additional job. 
Therefore, consider the type of work that users in a class 
perform. 

• Estimate the percentage of CPU time (or time purchased) each 
class should receive. This is a difficult step; however, you 
can experiment with and later alter the percentages you 
choose. (Sectiqn 10.1.5 describes how you can change class 
percentages.) If a class consists of a large number of users 
who are generally logged in at the same time, be sure to give 
this class sufficient CPU time. , For example, using the 
diagram below, class 2 has 60 members. It also has 60 
percent of the CPU. This means that if approximately 60 jobs 
in class 2 are demanding the CPU, each job will receive 
approximately 1 percent. (it may be slightly greater than 1 
percent if you allocate windfall.) This also means that on a 
per-job basis, users in class 2, with the higher percentage, 
may not get as much of the CPU as users in class or class 
1. 



CLASS 1 
CLASS 




CLASS 2 



• The above diagram illustrates that you can allocate less than 
100 percent of the CPU to classes. However, the total 
percentage for all classes cannot exceed 100 percent. 
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The system uses class as a default for any account that 
does not have a valid class assigned to it. Therefore, you 
can divide a portion of the system into well-defined classes 
and have all other users receive the percentage given to the 
default class. 

You can set up the class scheduler so that one class, perhaps 
the default class, receives only windfall. For example, 
suppose you allow some users to log into an account that is 
not yet assigned a class. These users are assigned to the 
default class 0. Or, suppose several users log in 
infrequently, read mail, and perform little computing. These 
users may log into an account that is not assigned a class 
(and, therefore, are assigned the default class, 0) , or an 
account that is associated with class 0. You subsequently 
assign a zero percentage to class 0. These users may receive 
enough windfall to get their job done. However, they are not 
allocated CPU time and can have periods of extremely slow or 
no response. You may find, after experimenting with this 
type of procedure, that it is better to associate each 
account with a class and give the class a very low percentage 
of the CPU. 

Situations may arise that affect the scheduler's ability to 
give a class its percentage of the CPU. For example, the 
members of a class cannot use the amount of CPU time 
allocated to the class. Also, a situation may arise where 
the demands of the class exceed the percentage of CPU time 
given the class, and windfall is available but not allocated. 
In either case, you should reevaluate both the percentages 
given to classes, and whether or not you want to continue 
withholding or allocating windfall. 



10.1.4 Procedures to Turn On the Class Scheduler 

After dividing users into classes and estimating the amount of CPU 
time, follow these steps to set up classes and turn on the class 
scheduler. 

STEP PROCEDURE 

1. Edit the <ACCOUNTS>ACCOUNTS.CMD file on the public structure 
(and the subaccount files, if any, that contain all your 
accounting data). Follow the procedure in Chapter 6, 
Creating Accounts, for modifying or creating each account 
with the /CLASSrn switch. For example, 

ACCOUNT C0MP1/CLASS:1 
USERS KOHN, HOLLAND, MILLER 

means that when users Kohn, Holland, and Miller log into or 
change their account to C0MP1, they are placed in class 1. 
Each account has only one class associated with it. 
Therefore, only the user who has access to more than one 
account can have access to more than one class. A job can 
be in only one class at any one time. 

2. Run the ACTGEN program. Give the TAKE command and specify 
the <ACCOUNTS>ACCOUNTS.CMD file (or the file containing the 
accounting data) . 
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When ACTGEN returns its prompt, give the INSTALL command. 
This command updates the ACCOUNTS-TABLE.BIN file that the 
system uses to validate accounts. 

Edit the n-CONFIG.CMD file to include the CREATE commands 
that specify the classes. Be sure account validation is 
enabled. That is, check that the DISABLE ACCOUNT VALIDATION 
command is NOT in the file. (The system default is 
ENABLED.) If account validation is disabled, users can use 
any account and therefore any class they choose. Enter the 
following commands in the order shown below. 

The CREATE command defines the class number and the 
percentage of CPU time the class should receive. For 
example, 

CREATE .40 

means that the default class, 0, should receive 40 percent 

of the CPU. Enter the CREATE command for each of the 

classes that you defined in the ACCOUNTS.CMD file. For 
example, 

CREATE .40 
CREATE 1 .20 
CREATE 2 . 30 

NOTE 

Remember that class is the default class. Any 

user whose account (this includes subaccounts) is 

not associated with a specific class is placed in 
class 0. 

Next, if you have decided to place all batch jobs in a 
separate class, enter the BATCH-CLASS command. For example, 

BATCH-CLASS 2 



means that all batch job 
regardless of the user's as 
CREATE command to define th 
batch class should receive, 
be in the same class as wel 
associated with that cla 
defines class 2 to receive 
you do not place a BATCH 
the scheduler treats all ba 
jobs. 



s will be placed in class 2 
sociated class. You must use the 
e percentage of CPU time that the 
Note that timesharing users can 
1, if the account they use is 
ss. The CREATE command in step 4 
30 percent of the processor. If 
command in the n-CONFIG.CMD file, 
tch jobs the same as timesharing 



Finally, enter the ENABLE CLASS-SCHEDULING command. Be sure 
this is the last command entered. If you reverse the order, 
that is, you enter ENABLE CLASS-SCHEDULING before the CREATE 
commands and BATCH command, all users will receive zero 
percent of the CPU. 
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The ENABLE CLASS-SCHEDULING command turns on the class 
scheduler at the next system reload. It also specifies if 
you are using accounting or an access control program 
(policy program) for class scheduling and if you are 
allocating or withholding the windfall. The format of this 
command is: 

ENABLE CLASS-SCHEDULING ACCOUNTS WITHHELD 

POLICY-PROGRAM ALLOCATED 

For example, 

ENABLE CLASS-SCHEDULING ACCOUNTS ALLOCATED 

means turn on the class scheduler, use the accounting 
method, and allocate the windfall. Always allocate the 
windfall. Do not withhold windfall unless you have a very 
good reason to do so, and you are sure that your class 
scheme works. 

The entry, 

ENABLE CLASS-SCHEDULING POLICY-PROGRAM ALLOCATED 

means turn on the class scheduler, use the policy (access 
control) program, and allocate the windfall. 

At the next system reload (the system is brought down and 
back up again) the new commands in the n-CONFIG.CMD file 
take effect. 



10.1.5 Changing Class Percentages During Timesharing 

During timesharing, you can change the percentage that a class 
receives by using the SET command to OPR. This change lasts until 
either the next system reload, or you make another change using the 
SET command. The format of the SET command appears: 

SET SCHEDULER CLASS (number) m (to percent) n 

n can be from 0-99 inclusive. Note that the decimal point required in 
the CREATE command is not allowed in this command. 

To make the percentage that a class receives permanent, edit the 
CREATE commands in the n-CONFIG.CMD file. For example, you can edit 
the commands 

CREATE .60 
CREATE 1 .30 
CREATE 2 .10 

to 

CREATE .10 
CREATE 1 .05 
CREATE 2 .80 

Next, reload the system to process the commands in the n-CONFIG.CMD 
file. The classes that received a low percentage before you made the 
change now receive a higher percentage of CPU time. 
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Changing class percentage may be useful if you decide that users in 
one or two classes should receive a greater percentage of CPU time 
than other classes during the day. However, these high-percentage 
classes may not require this time during the evening shift. If you 
have a recurring need for such changes, you may want to put the 
appropriate commands into files for use with the TAKE command in OPR. 



10.1.6 Disabling the Class Scheduler During Timesharing 

You can turn the class scheduler off and back on during timesharing by 
using the DISABLE and ENABLE commands to OPR. The class scheduler 
remembers the class percentages that were in effect before the DISABLE 
command was given. For example, suppose you use the SET command to 
change the percentage that class 1 should receive from 05 to 15 
percent. Then, you give the DISABLE CLASS-SCHEDULER command, and 
later give the ENABLE CLASS-SCHEDULER command. The class scheduler 
uses 15 percent for class 1. If you reload the system after disabling 
the class scheduler, the class scheduler is enabled again and uses the 
percentages given in the n-CONFIG.CMD file. 



10.1.7 Getting Information About Class Scheduler Status 

Several TOPS-20 commands provide information about different class 
scheduler statistics. 

The INFORMATION (ABOUT) SYSTEM-STATUS command informs you if: 

• the class scheduler is enabled or disabled 

• the accounting method or an access control program is being 
used 

• windfall is allocated or withheld 

• the system's batch jobs are in a separate class. 
For example 

@ INFORMATION (ABOUT) SYSTEM-STATUS<RET> 

CLASS SCHEDULING BY ACCOUNTS ENABLED, WINDFALL ALLOCATED, BATCH CLASS 1. 

The INFORMATION (ABOUT) MONITOR-STATISTICS command provides a table 
that shows each active class, its target use of the CPU, its current 
use of the CPU, and the load averages for that class. For example, 

@ INFORMATION (ABOUT) MONITOR-STATISTICS<RET> 

Class Share Use Loads 






0.80 


0.79 


6.56 


4.36 


3.57 


1 


0.15 


0.21 


5.46 


1.38 


.95 


2 


0.05 


0.00 


0.00 


0.00 


0.00 
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The SYSTAT command outputs load averages for either the entire system 
or a specific class. When the class scheduler is disabled, these 
averages represent the load of the entire system. For example, 

@SYSTAT<RET> 
Wed ll-Jul-84 10:17:09 Up 11:38:12 
52+16 Jobs Load av 5.30 4.03 4.86 

The last three numbers following Load av indicate the average number 
of runnable processes over a period of one minute, five minutes, and 
fifteen minutes. These numbers start at zero. The higher the numbers 
the longer a job has to wait for CPU time on the average. Using the 
example, over a fifteen minute period, a given job demanding the CPU 
waits approximately 4.86 times longer to run than it Would if it were 
the only job running on the system. 

When the class scheduler is enabled, these load averages represent the 
status of the job doing the SYSTAT command and not the entire system. 
For example, 

@SYSTAT<RET> 
Wed ll-Jul-84 10:28:07 Up 11:49:12 
52+10 Jobs Load av (class 1) 1.79 2.36 2.88 

The last three numbers following Load av indicate the load averages of 
the class that the job giving the SYSTAT command is in. The SYSTAT 
command with the CLASS argument provides a breakdown of each job on 
the system. This breakdown includes the class each job is in, the 
average share of the class percentage that this job can receive, and 
how much CPU time the job is currently using. 

The TOPS-20 Commands Reference Manual describes these commands in 
detain 



10.1.8 A Sample Session 
The following examples show: 

• The ACCOUNTS.CMD file after associating classes with 
accounts. 

• The procedures that you follow after editing all your 
accounting files. 

• A sample of the class scheduling commands that are placed in 
the 6-CONFIG.CMD file. 

!The <ACCOUNTS>ACCOUNTS.CMD file has been edited. 

$TYPE (FILE) MAIN:<ACCOUNTS>ACCOUNTS.CMD<RET> 

ACCOUNT MYBANK/CLASS:2 
USERS BLOUNT, KONEN,ENGEL 

ACCOUNT TRUST/CLASS :1 

USERS BRAITHWAITE, HURLEY, HALL, CRISS 

ACCOUNT OVERHEAD 

USERS SAMBERG,BERKOWITZ, TAYLOR 
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ACCOUNT PROG/CLASS: 3 
USERS BLO"NT,KOHN, HOLLAND 

$ 

INotice that account OVERHEAD uses the default class, 0. 

INext, run the ACTGEN program. 

$RUN ACTGEN<RET> 

ACTGEN>TAKE (COMMANDS FROM) MAIN: <ACCOUNTS>ACCOUNTS.CMD<RET> 

!After ACTGEN finishes and returns its prompt, give the 
! INSTALL command to create a new version of the 
!<SYSTEM>ACCOUNTS-TABLE.BIN file 

ACTGEN>INSTALL<RET> 

lAfter ACTGEN finishes and returns its prompt, give the 
J EXIT command 

ACTGEN>EXIT<RET> 
$ 

$TYPE SYSTEM : 6-CONFIG. CMD<RET> 

1 Terminal Speeds 

TERMINAL 1 SPEED 2400 

TERMINAL 2 SPEED 9600 

TERMINAL 3 SPEED 2400 

TERMINAL 4 SPEED 2400 

TERMINAL 5 SPEED 300 

TERMINAL 6 SPEED 300 

DEFINE SYS: MAIN: <SUBSYS> 

DEFINE SYSTEM: MAIN: <SYSTEM> 

DEFINE NEW: MAIN: <NEW>, SYS: 

DEFINE OLD: MAIN: <OLD>, SYS: 

DEFINE HLP: MAIN: <OLD>, SYS: 

MAGTAPE 24 

MAGTAPE 1 25 

PRINTER VFU SYS : NORMAL. VFU 

PRINTER LOWERCASE RAM SYS: LP 96. RAM 

TIMEZONE 6 

! Commands for the class scheduler 

CREATE .05 

CREATE 1 .45 

CREATE 2 .25 

CREATE 3 .15 

BATCH 3 

ENABLE CLASS-SCHEDULING ACCOUNTS ALLOCATED 



To start the Class Scheduler, either reload the system, or give the 
ENABLE CLASS-SCHEDULER command to OPR. If you edited the n-CONFIG.CMD 
file to remove the DISABLE ACCOUNT VALIDATION command, you must reload 
the system so you can start validating accounts. 
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10.1.9 An Alternative to Using Accounts 

Chapter 11 describes the access control program that is used to grant 
and restrict access to various system hardware and software. This 
same program can also include the appropriate monitor calls to handle 
class scheduler decisions. Some of the requests it can define are: 

• classes 

• class memberships 

• the batch class 

• class percentages 

• changing class percentages 

• windfall allocation per class 

The monitor calls that are required in this program are described in 

the TOPS-20 Monitor Calls Reference Manual . DIGITAL distributes a 

sample Access Control Job program that includes class scheduler 
monitor calls. 

This program is called ACJ.MEM and is located on the Distribution tape 
in the documentation area. The ACJ.MEM file provides you with a guide 
for writing your own access control program. Do not copy it and try 
to use it as is. 

NOTE 

You CANNOT run the access control program to implement 
class scheduler decisions at the same time you use the 
accounting method. You must use one or the other. 



10.2 SCHEDULING LOW PRIORITY TO BATCH JOBS 

The decision to favor batch jobs or to run them as background tasks 
depends on the type of batch environment you have at your 
installation. For example, if users submit batch jobs that are long 
and/or that do not require completion immediately, you can give batch 
jobs a low priority. Conversely, if batch jobs are the primary jobs 
on the system, you can give them a high priority. 

Section 10.1 describes how to place batch jobs in either a high or low 
percentage class by including the BATCH n command in the n-CONFIG.CMD 
file. When a user submits a batch job, the scheduler uses the batch 
class and not the user's class. 
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You must use the class scheduler to give batch jobs a high priority. 
If you are not using the class scheduler, you can give batch jobs a 
low priority. To do this, enter the 

BATCH-BACKGROUND 

command in the n-CONFIG.CMD file. This command specifies that all 
batch jobs run on the lowest priority queue, also known as the 
background queue. This means that after processing all interactive 
jobs, the scheduler selects and runs batch jobs waiting in the queue. 
They receive left-over CPU time. You can enter the BATCH-BACKGROUND 
command into the n-CONFIG.CMD file. The command takes effect the next 
time you reload the system. 

NOTE 

The BATCH-BACKGROUND command is intended for those who 
are not using the class scheduler on their system but 
want to give the batch jobs a low priority. You 
should not use this command when you enable the class 
scheduler. 



10.3 FAVORING INTERACTIVE VERSUS COMPUTE-BOUND PROGRAMS 

This section describes how you can influence the scheduler to favor 
either interactive or compute-bound programs. You do this by using 
the bias control, which is analogous to turning a knob over a range of 
settings (from 1 to 20). When you select a lower number, the 
scheduler favors users running interactive programs. When you select 
a higher number, the scheduler favors users running computational 
programs. Figure 10-1 illustrates this concept. 

BIAS CONTROL 



INTERACTIVE < \ > COMPUTE BOUND 




THE "KNOB" 



Figure 10-1: Bias Control 'Knob' 
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NOTE 



You can use bias control with or without the class 
scheduler enabled. However, the effect of the bias 
control is less noticeable when used with the class 
scheduler. 

After you install TOPS-20 software, the system uses the default bias 
control number 11. This setting distributes the scheduler's attention 
evenly to interactive and compute-bound programs. 

New users of TOPS-20 can use the default setting until they need to 
favor particular types of programs. Previous users of TOPS-20 may 
want to experiment with new control settings. For example, the bias 
controls can serve as a good tool for favoring different types of 
users at different times of the day. For instance, you can set the 
bias to a low number during the day to favor on-line users and to a 
high number during the evening to favor batch users. The response you 
receive from your user community should determine the appropriateness 
of the selected settings. 

Setting the bias toward interactive programs gives better response to 
the terminal user. Also, this setting may produce a higher system 
overhead, because the scheduler swaps jobs and switches from different 
tasks more often in its effort to favor interactive programs. 
Generally, setting the bias toward interactive programs is beneficial 
only if you have sufficient memory. Both the swapping rate and the 
scheduler overhead are likely to increase in small systems with too 
little memory. If your system has adequate memory, the scheduler 
overhead should be fairly constant over most of the bias settings. 

Setting the bias toward computational programs should reduce system 
overhead and increase the total system throughput. However, the 
response to the terminal user may decrease slightly. In some cases, 
the improvement in system throughput more than compensates for the 
lessened response time, and users are more satisfied. 

As you experiment with the bias settings, remember that setting the 
bias control to the extremes can prevent certain types of programs 
from running for long time periods. 

After you select a bias control number that fits your system's 
operation, enter the BIAS CONTROL command in the n-CONFIG.CMD file or 
use the SET SCHEDULER BIAS-CONTROL command to the OPR program. 

The format of the command in the n-CONFIG.CMD file is: 

BIAS CONTROL m 
The format of the command to OPR is: 

SET SCHEDULER BIAS-CONTROL (TO) m 

where m is the bias control number. 

You can change the bias setting during timesharing by using the SET 
SCHEDULER BIAS-CONTROL command. However, when you reload the system, 
the bias setting in the n-CONFIG.CMD file takes effect. If you want 
your change to be permanent, edit the n-CONFIG.CMD file at a 
convenient time before you reload the system. 

Any time you are unsure of the current setting of the bias control, 
give the INFORMATION (ABOUT) SYSTEM-STATUS command to determine its 
setting. 
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10.4 IMPROVING PROGRAM STARTUP TIME 

Some of the programs on your system are run frequently. This involves 
constant searching for the same file on disk, bringing the program 
pages into memory, and allocating swapping space when the program is 
swapped out of memory. By storing these programs in an easy-to-access 
area, some of the startup time is saved. To improve the startup time 
of the frequently used system programs, TOPS-20 keeps a program name 
cache. 

The <SYSTEM>PROGRAM-NAME-CACHE.TXT file is placed in the directory 

<SYSTEM> on the public structure automatically at installation time, 

and contains a list of programs and files to be copied into the 
program name cache. These are: 

SYS: PA1050.EXE 
SYS:MACRO.EXE 
SYS: EDIT. EXE 
SYS: TV. EXE 
SYS:LINK.EXE 
SYSTEM: ERRMES.BIN 

Each time you reload the system, the <SUBSYS>MAPPER.EXE program runs 
under the SYSJOB program at the operator's console. 
<SUBSYS>MAPPER.EXE reads the <SYSTEM>PROGRAM-NAME-CACHE.TXT file and 
loads the program name cache. Now, when requests are made for these 
programs, the system looks first in the program name cache to see if 
it can retrieve the required pages quickly. 

To further improve system performance, you can edit the 

PROGRAM-NAME-CACHE.TXT file and add the filenames of your own 

frequently accessed programs. For example, if your system uses the 

FORTRAN language, you may want to add the files: 

SYS: FORTRA.EXE 
SYS: FOROTS.EXE 
SYS:FORLIB.REL 

Your list can contain the names of up to 16 executable files. 
Therefore, select the files to be placed in the program name cache 
carefully. You should consider only the executable files that are 
started frequently by a large number of users. 

You can also add library files to the program name cache, for example, 
SYSsFORLIB.REL. However, these types of files use up swapping space. 
If you have too many or very large files, you may create a detrimental 
effect on your system's performance. The total library file pages 
that you cache should be no greater than 200 to 300. Give the 
VDIRECTORY command for the library files you want to cache and check 
the number of pages in each file. 
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If you edit the cache file, the revised file takes effect (MAPPER 
creates a new version of the cache) the next time you reload the 
system. Alternatively, you can create a new version of the cache 
immediately by entering the following commands at the operator's 
console. 



ESPEAK 
KILL MAPPER 
RUN SYS:MAPPER.EXE 



I talk to SYS JOB 
Ikill old version of cache 
I read new file and create 
!new version of cache 
lex it 



10.5 REINITIALIZING DISK PACKS 

After many files are created, they may no longer be contiguous on the 
structure (disk(s)). This scattering of files may increase the time 
it takes to process them. You may decrease processing time by 
reinitializing the disk packs in your heavily used structures. For 
example, the public structure may be a likely candidate for 
reinitialization. This procedure places files into a contiguous 
format and can be scheduled as part of a backup procedure. How often 
you reinitialize your packs depends on the work load of the system and 
whether you notice a difference in system performance after following 
this procedure. 

Reinitializing disk packs requires that you dump all the directories 
and files to tape, re-create the structure (and, in the case of the 
public structure, reinstall the system) , and restore all the 
directories and files. Therefore, if you do not notice any 
appreciable difference in your system performance after doing this, 
don't schedule it on a regular basis, if at all. 

The TOPS-20 Operator' s Guide describes re-creating the public 
structure and other structures. Have the operator use this procedure 
for reinitializing disk packs. If possible, have the operator 
re-create the structure and restore the files to a different pack (or 
set of packs) from the structure that you dumped. This ensures that 
you do not lose your files should you have problems reading the tape 
back to disk. That is, you still have the original structure intact 
and can run DUMPER again to copy the files to another tape. 



10.6 DYNAMIC DUAL PORTING 

Dynamic dual porting refers to a disk drive that is dual-ported to one 
system only. When one of the channels is busy transferring data for 
another disk unit, input/output is automatically switched through the 
other disk channel. Dynamic dual porting improves the performance of 
input and output operations. It is activated automatically after 
field service properly sets up the RP04, RP06, or RP07 disk drive(s) , 
and the operator places the drives' port switches in the A/B position. 



Dynamic dual porting is not supported for RP20 disks, 
jobs could hang, files could be damaged, and so on. 



If it is tried, 



The DECSYSTEM-20 Technical Summary describes the hardware associated 
with input and output operations. 
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CHAPTER II 
ACCESS CONTROLS 

TOPS-20 provides control mechanisms that help you: 

• Govern the access to many of your system's resources and 
services 

• Reduce or prevent unauthorized access to the system 

• Investigate occurrences of unauthorized access 
The following sections discuss these topics. 

11.1 ACCESS CONTROL PROGRAM 

Previous chapters deal with administrative policies for allocating 
resources. For example, Chapter 10 describes the policy decisions you 
can make regarding the scheduler, and Chapter 8 describes the policy 
decisions you can make regarding tape drive allocation and labeled 
tape support. 

In addition, you can make policy decisions that govern the access to 
specific system resources. For instance, TOPS-20 allows a user to 
change the speed of a terminal, assign a device, log in at any time of 
day, mount a magnetic tape, and mount a disk structure. However, you 
may want to restrict or disallow use of some of these facilities. You 
may want only specified users at specified times of the day and, 
perhaps, at specified terminals, to use certain facilities. A 
particular mechanism lets you control the access to such resources and 
services. With it, you have an additional means for collecting 
accounting or other information. 

To use this access control mechanism, you must write an access control 
program that carries out your policy decisions. An access control 
program can control scheduling classes, the bias control, batch 
background queue, logging in, use of physical resources (tape drives, 
terminals, structures), and enabling capabilities. When a user 
requests a resource (like ASSIGN TTY34:), your program identifies the 
user, the user's controlling terminal, and the type of request being 
made. Your program can merely log this information in a file, or make 
a decision and tell the monitor to either grant or deny the request. 

DIGITAL provides the necessary mechanisms (monitor calls) to implement 
a program at your installation. Your system programmer uses the 
appropriate monitor calls to write an access control program according 
to the requirements of your system. A sample access control program 
(ACJ.MEM) is distributed in the documentation area on the distribution 
tape. Your system programmer can use this program as a sample of the 
structure of an access control program and the parameters and 
decisions that can be controlled. 
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The following list defines the resources that an access control 
program can control and explains why you may want to control them. 

Assign Devices 

You can restrict users from assigning terminal lines or tape drives to 
their jobs. For example, if you have not enabled tape drive 
allocation (described in Chapter 8) , you may still want to control 
which users are allowed to assign tape drives. Your program can also 
prevent one user from assigning all the available tape drives or 
terminals. 

Enable Capabilities 

You can allow users to enable their capabilities only in certain 
locations, or perhaps only at certain times of the day. For example, 
in a university environment, you may not want users; enabling WHEEL 
capabilities in a terminal room used by students. In an environment 
where security is a major concern, you may want to allow a user to 
enable WHEEL capabilities only on a hard-copy terminal and only in a 
certain location. You can then collect the hard-copy output from the 
terminal. The access control program can also keep a file of the 
names of people who have enabled their capabilities. 

Create Jobs 

You can restrict the users who are able to write programs that create 
additional jobs via the CRJOB monitor call. You may want to limit 
this facility to certain applications only. 

Allow Login 

You can prevent users from logging in more than once, or permit a user 
to log in only at certain times of the day. For example, in a 
university environment, it may not be desirable to have students on 
the system during large production runs. Also, if you use your own 
accounting information (and not that provided with TOPS-20) , you can 
use the access control program with the login function to recognize a 
user. In addition, the login function can be used to control the 
number of jobs that a user can create under PTYCON. 

I Create Processes (Forks) 

You can prevent a user from creating more than a predefined number of 
processes. Also, you may want to charge users for using many 
I processes. 

Set Terminal Baud Rate 

You can control the input and output speed settings on all terminals. 
This control prevents users from changing the baud rate to a speed 
that is unsupported by the terminal, and, as a result, rendering the 
terminal unusable until the operator resets the baud rate. You can 
also restrict the speed of a terminal to no more than a specified 
maximum, for example, 300 baud. 
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Logout 

You can request the access control program to notify you or record 
information in an accounting file each time a user logs off the 
system. You may also want to keep track of the users who log out and 
are over their permanent disk page quota. The access control program 
can notify the operator that a migration-trim-run is needed for this 
directory to bring the directory back under its quota. If you use the 
login function with the logout function, you can give the user who is 
logging out information about time, resources, and perhaps money 
spent. 

Set ENQ Quota 

TOPS-20 allows enabled WHEELS to change to ENQ-DEQ quota. By using 
the ENQ quota function in your access control program, you can allow 
users other than WHEELS to change the ENQ-DEQ quota. (The TOPS-20 
Monitor Calls Reference Manual describes the uses of ENQ-DEQ.) 

Create Directory 

You can prevent users from giving the BUILD, SET DIRECTORY, or 
~ECREATE command to create directories or change parameters. Or, you 
may simply request the access control program to notify you of the 
people who have used these commands. You may want the operator to 
police these directories and check the parameter changes. 

Mount a Structure 

You can control access to certain structures by allowing only a select 
group of users to c|ive the MOUNT command for a particular 
structure(s) . This facility is used in conjunction with regulated 
structures. (The TOPS-20 Operator's Guide describes REGULATED and 
NON-REGULATED structures.) Also, information about structure mounts 
can be recorded in accounting files. 

Enter MDDT 

You can disallow privileged users from entering MDDT mode. For 
example, during certain times of the day, you may not want enabled 
WHEELS looking at or fixing a problem in the monitor. You may also 
want to keep a record of who has used MDDT. 

Class Assignment 

You can prevent users from changing to unauthorized scheduling 
classes. The access control program determines the classes a job can 
use. 

Set Class at Login 

The access control program can set a user's class at log in. Your 
program can contain (or access a file that contains) the list of users 
and their associated class. 

MT Access' Request 

You can have the access control program decide whether a user should 
be allowed to access a restricted labeled tape from a non-TOPS-20 
system. For example, if a non-TOPS-20 labeled tape is mounted with a 
nonblank access code in the access field, you can have your program 
decide if this user can use this tape. (The TOPS-20 Tape Processing 
Manual describes the access fields on labeled tapes.) 
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ACCESS/CONNECT Request 

The access control program can determine if an ACCESS or CONNECT 
request to a directory should succeed in cases where the request is 
denied by the monitor. For example, the TOPS-20 monitor allows an 
ACCESS or CONNECT request to succeed when appropriate criteria are 
met. These are: 

• The requesting process has WHEEL or OPERATOR capabilities 
enabled. 

• The target directory is in the same group as the job's 
"accessed" directory. 

• The target structure is DOMESTIC and the target directory 
name matches the logged-in directory or the job. 

• The correct password is specified. 

If all of the above criteria fail, the monitor denies the request. 
The access control program can be called to approve or override the 
denial. 

ATTACH Request 

The access control program can prevent a user from attaching his 
terminal to another job. This function allows the access control 
program to control which terminals can attach to specific jobs. 



11.2 PASSWORD ENCRYPTION 

One way to violate system security is through unauthorized use of 
directory passwords. Having acquired someone's password, an intruder 
could log in or gain access to restricted system resources. The 
password encryption facility in TOPS-20, however, makes it harder to 
steal passwords. 

With encryption enabled, passwords entered into the system are 
translated to an indecipherable cyphertext format before they are 
stored or otherwise used. Nowhere in the system is the original 
plaintext form of a password kept. As a further security measure, no 
current TOPS-20 utility converts the cyphertext to plaintext. 

NOTE 

Password encryption is irreversible. Therefore, 
before enabling encryption, be sure you will never 
need to revert back to an earlier version of the 
operating system. 

To enable password encryption, use the CHECKD program. You can do 
this during or after system installation. (Refer to the TOPS-20 KL 
Model B Installation Guide for details.) With CHECKD, password 
encryption is enabled on a structure-by-structure basis; after the 
procedure, all passwords for x a particular structure are encrypted as 
previously described. If you enable encryption after installation, 
run the KRYPTN program after CHECKD to convert existing plaintext 
passwords on a structure to cyphertext. The KRYPTN program is located 
on the tools tape, which is part of the TOPS-20 software installation 
package. 
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Encryption should be enabled for all structures except those that will 
be used on a TOP8-20 pre-Version 6 system. (Section 11.2.1 discusses 
this topic.) 

You can add your own encryption algorithm to the system if you choose 
not to use TOPS-20's algorithm. Refer to Section 11.2.2. 

Because the encryption algorithm is irreversible, care is required in 
the following areas: 

• Remembering one's password 

• Working in a multiple-system environment 

• Adding new algorithms to the system 

• Using DUMPER 

Mistakes in these areas could invalidate passwords so that they may 
need to be respecified with BUILD or ~ECREATE. These interrelated 
topics are discussed in the following sections. 



11.2.1 Moving Structures Among Systems 

If you are in a multiple-system environment, you may need to move 
structures from one system to another. Problems could arise, however, 
if some systems are running TOPS-20 pre-Version 6 software and others 
are running TOPS-20 Version 6. For example, when a structure 
containing encrypted passwords is taken to a TOPS-20 pre-Version 6 
system, any access to files on the pack that requires a password to be 
supplied fails, because, in validating a password, the older monitor 
simply compares the entered plaintext to the cyphertext stored on 
disk. The older monitor is unfamiliar with the encryption process. 

To avoid this problem, you should postpone encryption for relevant 
structures until all systems are upgraded. 

Any TOPS-20 system can correctly handle unencrypted structures. 

You could also encounter problems in moving structures to other 
systems if you use your own encryption algorithm. This topic is 
discussed below. 



11.2.2 Adding Encryption Algorithms to the System 

You can use one or more of your own encryption algorithms exclusively 
or in addition to TOPS-20's algorithm. For a description of the 
procedures involved, refer to the monitor module, STG.MAC. 

Each time a password is encrypted and stored in a directory, the 
version number of the algorithm used to encrypt it is also stored. 
This allows new encryption algorithms to be added to the system with 
no impact on currently encrypted passwords, provided the old 
algorithms have not been removed from the monitor. Only passwords 
created since the installation of the new (current) algorithm will be 
encrypted with that algorithm. Older passwords invoke the appropriate 
algorithms during password-required accesses. 
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If you also want existing passwords to use the new algorithm, the 
operator must individually respecify the passwords with BUILD or 
"ECREATE. The operator does this after the new algorithm is 
installed. Note that KRYPTN cannot be used here to convert existing 
cyphertext to new cyphertext. 

In using your own encryption algorithms, be aware that directories on 
structures and on DUMPER-created tapes include passwords that may be 
unusable at other sites. Other TOPS-20 monitors could consider the 
passwords' algorithm version numbers to be invalid. For example, 
these monitors may acknowledge only the standard TOPS-20 algorithm. 
Even if a site accepts the version numbers, its corresponding 
algorithms may be different from the algorithms at your site. Thus, 
on attempted password use, the cyphertext produced at this other site 
could never match the stored cyphertext. 

To address these problems, you could: 

• Warn sites about the nature of the passwords on a tape or 
structure. A site could then avoid using certain directories 
or respecify a password with BUILD or "ECREATE if necessary. 

• Refrain from saving directory information on tapes bound for 
other sites. That is, do not use DUMPER' s CREATE command 
when creating such tapes. 

• Ship only directories that have null passwords. These 
"passwords" are considered unencrypted, and should cause no 
problem on any system. 



11.2.3 Using DUMPER 

Section 11.2.2 addressed using DUMPER with nonstandard 
This section continues the discussion of DUMPER. 



algorithms. 



Care must be taken when restoring directories that were saved with 
DUMPER's CREATE command. Incompatible versions of tapes, DUMPER, and 
TOPS-20, when combined, can produce a number of password-related 
problems. Note the system's behavior -during tape restoration for the 
combinations in Table 11-1. In the table, tape Version 4 is the 
version of tape that DUMPER Version 4.1 creates. Tape Version 5 is 
the version of tape that DUMPER Version 5 creates. 



Table 11-1: DUMPER Directory Restorations 



Tape Version 


DUMPER 


MONITOR 


Result 


5 


5 


6 


OK 


4 


5 


6 


OK (Nl) 


5 


4.1 


6 


El 


4 


4.1 


6 


OK (Nl) 


5 


5 


5 


E2 


4 


5 


5 


OK 


5 


4.1 


5 


E3 


4 


4.1 


5 


OK 
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Legend: 

Nl Passwords are correctly encrypted for the first time using 
the monitor's current encryption algorithm. 

El The tape version number is incompatible with this DUMPER. 
DUMPER reports this fact before restoring the tape data. If 
directories are restored from this tape, encrypted passwords 
are re-encrypted, causing all uses of these passwords to 
fail. The passwords will then have to be individually 
respecified with BUILD or "ECREATE. However, if a password is 
unencrypted on the tape, then it is encrypted for the first 
time, and will be usable. 

Any files on this tape are restored correctly. 

E2 Pre-version 6 monitors have no logic to handle 
encryption-related data that the tape may contain. Therefore, 
restored encrypted passwords are unusable and must be 
respecified with BUILD or "ECREATE. Note that directory 
blocks on the tape may contain password descriptor 
information, such as the encryption version number. This 
descriptor data is not restored. 

Any files on this tape are restored correctly. 

E3 The tape version number is incompatible with this DUMPER. 
DUMPER reports this fact before restoring the tape data. This 
incompatibility results in the same situation as E2. 

If these problems occur offten, users and operators could refrain from 
saving directory information on tapes, or they could use null 
passwords for directories that are to be saved. Null passwords are 
considered to be unencrypted and should cause no access problems. 



11.3 PASSWORD MANAGEMENT 

Encryption is just one part of password management. You should also 
make sure that users at your site do not choose passwords that are too 
short or that are otherwise easy to guess, such as one's name or 
initials. Also, it would be helpful for users to change their 
passwords regularly. 



11.4 LAST LOGIN INFORMATION 

When users log into the system, the dates and times they last logged 
in are displayed on their terminals. This information helps alert 
them to instances of illegal system or account entry. For example, if 
users keep track of their actual login times, they can compare those 
times to the ones displayed. Then, if there is a discrepancy, they 
will know the exact time that someone else logged into their directory 
using their password. 
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11.5 PREVENTING FAST LOGINS 

By using the /FAST switch with the LOGIN command, users can bypass 
processing of their LOGIN.CMD and COMAND.CMD files. Managers 
sometimes set up these files to limit users' computing environments, 
however. For example, sets of users may be allowed only to read mail 
or run some other computer application. You can prevent fast logins 
at your site by entering the following command in the n-CONFIG.CMD 
file: 

DISABLE FAST-LOGIN-OPTION 

The ENABLE FAST-LOGIN-OPTION command is in effect by default. You can 
also enable and disable fast logins with the "ESET privileged command. 

Refer to the TOPS-20 User's Guide for information on the LOGIN.CMD and 
COMAND.CMD files. The TOPS-2 Commands Reference Manual describes the 
LOGIN command. 
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CHAPTER 12 
THE COMMON FILE SYSTEM 



12.1 OVERVIEW 

The Common File System (CFS) is a feature of TOPS-20 that allows users 
from more than one system to simultaneously access files. Any 
structure in the CFS configuration can be made available to any user 
for reading or writing. 

Each TOPS--20 system in the CFS configuration has its own operating 
system, main memory, public structure, console, unit-record devices, 
and processes to be scheduled and run. But the systems are linked 
through a shared file system. This unified file system can be 
composed of all the disk structures on all systems. These structures 
appear to users as local to their own systems. 

The main features of CFS are: 

• It increases file accessibility. For example, if a system is 
down for maintenance, users can log onto another system and 
still access all files that do not depend on the down system 
for access. 

• It lets you adjust loads on systems by reassigning users as 
loads require. (Or, users themselves may be allowed to 
switch systems as they see fit.) These changes need not 
result in file-access limitations. 



• It lets you reduce the time that would be 
maintaining duplicate sets of files. 



involved in 



• It lets you save disk space by minimizing duplication of 
files on different systems. 
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12.1.1 CFS HARDWARE 



I 

I The following are typical CFS configurations: 





DECSYSTEM-20 




| CI-20 | 



Star Coupler 



DECSYSTEM-20 
Tll-20 1 




MR-S-3905-85 



Figure 12-1: Two Systems with Massbus Disks and HSC50-based Disks 
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Star Coupler 



Figure 12-2: Two Systems with Massbus Disks 

Star Coupler 

The star coupler provides the physical interconnection for the CI 
cables among DECSYSTEM-20s" and HSC50S. The maximum distance between a 
system and the star coupler is 45 meters. 

A DECSYSTEM-20 can be connected to just one star coupler. That is, it 
can be part of only one CFS cluster. 

CI 

The Computer Interconnect (CI) bus is the communications link used by 
CFS. It also connects systems to HSC50-based disks (RA60s and RA81s) . 
In addition, it provides access to massbus disks for systems without a 
direct connection to those disks, for example, to another system's 
public structure. 

Each system has four communications links to the star coupler. Two of 
them are for transmitting data and the other two are for receiving 
data. The redundant CI connections are used for increased 
availability and performance. When one of the connections has failed 
or is in use, the CI microcode chooses the other one for data 
transmission. At start-up, TOPS-20 verifies that at least one set of 
transmit and receive connections is working. 



CI20 



The CI20 port adapter provides the interface between the 
and the CI bus. Only one CI20 is allowed per system. 



DECSYSTEM-20 
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Massbus Disks 

Multi-system access may be granted to all massbus disks. 

It is recommended that massbus disks intended to be shared be 
dual-ported between two DECSYSTEM-20S (drive port switches placed in 
the A/B position). With a two-system CFS cluster, this avoids the 
overhead involved in file- server activity, as described later in this 
section. However, the systems must be able to communication with each 
other over the CI; they must be connected to the same star coupler. 
Otherwise, neither system will be allowed access to the disk. Thus, 
the following configurations are not supported: 





MH-S-3916-B5 




MR-S-3917-B5 



In the first two figures, systems G and H are not joined in a CFS 
configuration. The same applies to systems H and I in the third 
figure. TOPS-20 maintains the integrity of data on shared disks by 
ensuring that the systems can, over the CI, coordinate accesses to 
those disks. 
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Massbus disks not directly connected to a system are called " served 
disks " because TOPS-20's MSCP (Mass Storage Control Protocol) 
file-served facility makes this "outside" access possible. To enable 
an outside path to a massbus disk, that is, to make it a served disk, 
enter an ALLOW command in the n-CONFIG.CMD file, on a system to which 
the disk drive is connected, in the form: 

ALLOW <drive type> serial number 

The drive type is one of the following: RP04 , RP06, RP07, or RP20. 
You can obtain the serial number with the command: 

OPR>SHOW CONFIGURATION DISK-DRIVE 

Note that TOPS-20 creates an RP20 serial number by adding 8000 to the 
disk drive unit number. Therefore, RP20 unit numbers should be unique 
among CFS systems. 

NOTE 

Disks that make up the public structure must not be 
dual ported to another TOPS-20 system. 



12.1.2 CFS SOFTWARE 

Intersystem communication is an integral part of CFS. When TOPS-20 
starts up, it makes a CFS connection with each TOPS-20 system that is 
already running. This establishes the contact necessary for 
intersystem file-system management. 

In reality, only one system writes to a 256K section of a file at a 
time. When a system needs write access to a file section, it 
broadcasts a request for that resource to all systems it has 
established contact with. If another system already owns the desired 
write access, that system will respond negatively. Clearance will be 
granted to the requesting system only after the other system has 
completed the write operation by writing the data back to disk from 
its memory. Thus, systems negotiate for write access to files and 
keep each other informed of the state of the disks that they share. 
This ensures the integrity of data on those disks. 

Because intersystem communication is vital to CFS operations, the 
systems stay alert to CI problems and to other indications that they 
may have lost contact with each other. Section 12.11.1, Communication 
Problems, discusses the actions that systems take when there is a 
breakdown in communications. 

The INFORMATION CLUSTER command displays the names of HSC50S and CFS 
systems that are currently accessible. 
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DATE and TIME 

When a CFS system starts up, it takes the date and time from the 

systems that are already running. The operator is not prompted for 

this information. Instead, the system types a message similar to the 
following on the operator's terminal: 

The date and time is: xxxxxxxxxx 

This typeout serves as a check on the date and time. If no other 
system is running, the operator is prompted for the information. 

When the date and time are changed on any CFS system, such as with the 
"ESET command, all other systems are notified so that they can 
re-synchronize. This synchronization ensures that the creation date 
and time of files written from one system are consistent with the 
other CFS systems. Otherwise, many programs that use this information 
could malfunction. 



12.1.3 CFS USERS 

CFS is transparent to users: 

• Users are normally unaware that someone from another system 
may be accessing a file at the same time that they are, 
except in such cases as the following. A file being read on 
system "A" will prevent its being renamed on system "B." 

• Users are not required to know about the CFS configuration. 
Specifically, they do not need to know how massbus disks are 
ported. To access files, all they need to know are structure 
names, as on non-CFS systems. 

The INFORMATION CLUSTER command lets users know what HSC50S and 
TOPS-20 systems are currently accessible to their systems. 



12.1.4 CFS and DECnet 

A CFS configuration differs from a DECnet network. Although a CFS 
configuration comprises multiple independent systems, the systems 
share a unified file system and cooperate in its operation. They 
function more as a single system than as systems merely communicating. 
If the optional DECnet-20 software is installed, each CFS system 
running DECnet is a DECnet network node with its own node name. 

The files in CFS disk structures may be accessible to remote systems 
by way of such DECnet facilities as NFT. However, a node name is 
needed to access files in this way. CFS users, on the other hand, do 
not need to specify node names. 

All systems in a CFS configuration must be TOPS-20 systems. In a 
DECnet network, however, other systems that support DECnet can be 
included. 

DECnet on a system allows access to other CFS clusters as well as 
DECnet communication between systems in a cluster (for example, with 
the SET HOST command) . 
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Table 12-1: Comparison of CFS and DECnet 



Characteristic 


CFS 


DECnet 


Multiple systems 


X 


X 


TQPS-20 systems only 


X 




One file system 


X 




Node name in file spec 




X 


DECnet software 




X 


CI 


X 


X 


NI 




X 



12.1.5 CFS and TIGHTLY-COUPLED SYSTEMS 

A CFS cluster also differs from tightly-coupled multiprocessing 
environments. Each CFS system has its own main memory, which is not 
shared with another system. It also has its own public structure for 
booting, logging in, and swapping. Also, CFS systems do not perform 
automatic load balancing. That is, the CPUs do not relieve each other 
of processing during high job loads. All jobs, including batch jobs, 
run only on the computer that the user logs onto. 



12.1.6 Limitations 

CFS does not coordinate use of the following facilities across 
systems: ENQUEUE/DEQUEUE, IPCF, and OPENF OF%DUD. As an example, a 
DBMS application cannot span multiple systems, because DBMS uses the 
OPENF OF%DUD facility. Therefore, such applications should be 
restricted to a single system. Attempts to cross systems using these 
facilities will generate error messages. 

CFS allows for shared disk files only. It does not provide for shared 
magnetic tapes and line printers. Thus, for example, all of a user's 
printing will be done on a line printer that is attached to his 
system, even if he prints a file that resides on a server disk. 



12.2 PLACEMENT OF FILES 

This section offers guidelines for arranging files on CFS systems for 
maximum performance and efficiency. 
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12.2.1 Update Files 

Simultaneous shared writing to a file from multiple systems incurs the 
most overhead of any CFS file access operation. This is because 
systems involved in shared writing spend time seeking and granting 
write permission and coordinating their moves in other ways. 
Therefore, you might want to place the involved users on the same 
system. 



12.2.2 Files on Served Disks 

For optimum performance, you should not place on served disks files 
that require frequent access from multiple systems. This applies to 
both reads and writes. MSCP file-server operations incur considerable 
overhead, because the system with the direct connection acts as a disk 
controller for the accessing system. Therefore, such files should 
reside on HSC50 disks or, in a two-system CFS configuration, on 
massbus disks dual ported between systems. 



12.2.3 Mail Files 

By default, users' mail files are created and updated in their 
logged-in directories on the public structure. To access this mail, 
users log in and issue appropriate mail commands. They may have to go 
through this login procedure for every system that contains mail for 
them. You can change this default arrangement and simplify matters 
for the CFS user who has accounts on multiple systems. By redefining 
the system-wide logical name POBOX:, as described in Section 3.3.9, 
you can establish a central location on a sharable structure for all 
mail files in the CFS configuration. Then, no matter where users log 
in, the mail facility sees an accumulation of mail that could have 
been addressed to them at any system in the configuration. Mail is no 
longer isolated on individual public structures. 

An added advantage to redefining POBOX: is that public structures do 
not fill up with mail files. 

You must create a directory on the structure defined by POBOX: for 
every user in the CFS configuration who is to receive mail. 



12.2.4 Sharing System Files 

Most of the files that normally reside on public structures can be 
moved to a shared structure. Rather than duplicate files in such 
areas as SYS: and HLP: across systems, you can keep one set of these 
files on a shared structure. Thissaves disk space and eases the task 
of maintaining the files. Also, time and tape are saved during DUMPER 
backup and restore operations. Because system files are primarily 
read and not often updated, system performance does not suffer because 
of this file sharing, provided the structure is not on a server disk. 
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If you consolidate system files, remember to include in the 
definitions for the system-wide logical names the structures that 
contain the files. For example, if the SYS: files reside on the 
structure COMBO:, the definition for SYS: would be: 

DEFINE SYS: <AS) COMBO ! <NEW-SUBSYS> , COMBO: <SUBSYS> » MAIN ! <NEW-SUBSYS> , MAIN '. <SUBSYS> 

where 

MAIN: is the name of a public structure 

You should define structures in this way on all the systems, giving 
the appropriate public structure name. Make sure that the shared 
structure or structures are mounted UNREGULATED so that users will be 
able to access the files without having to give a MOUNT command. 

The drawback to sharing system files is that if there is trouble with 
the shared structure, users on all systems suffer. 

Most of the SYSTEM: files must remain on the public structures, so 
sharing these files is not recommended. 

START-UP FILES 

Certain files must remain on each public structure. These files are 

involved in system start-up and are required before a non-public 

structure is made available to a system. The following files should 
remain in each <SYSTEM> area: 

6-1-CONFIG.CMD 

6-1-PTYC0N.AT0 

6-1-SETSPD.EXE 

6-1-SYSJOB.EXE 

6-1-SYSJOB.RUN 

ACCOUNTS-TABLE . B IN 

CHECKD„EXE 

DEVICE-STATUS.BIN 

DUMP. EXE 

ERRMES.BIN 

EXEC. EXE 

HOSTS.TXT 

IPALOD.EXE 

KNILDR.EXE 

MONITR.EXE 

MONNAM.TXT 

TGHA.EXE 

In addition, all the GALAXY files should remain in each <SUBSYS> area. 
These files come from the GALAXY saveset on the TOPS-20 Distribution 
Tape. (Refer to the TOPS-20 KL Model B Installation Guide .) 

Command files that are used at your installation during start-up also 
should be kept on separate public structures. These files include 
SYSTEM.CMD and NETWORK.CMD. 
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12.3 LOAD BALANCING 

This section discusses the distribution of jobs across CFS systems. 



12.3.1 Dedicating Systems 

One way to balance loads is to establish the types of jobs that will 
run on particular systems. For example, you might relegate batch jobs 
to one system, freeing other systems to run interactive jobs 
unimpeded. To encourage users to adopt this arrangement, you could 
give batch jobs the lowest priority on all but the batch-designated 
system. Users will have to wait a relatively long time for completion 
of batch jobs on non-batch systems. Refer to Section 10.2, SCHEDULING 
LOW PRIORITY TO BATCH JOBS, for further information. 

Conversely, on the batch system, you could accord batch jobs the 
highest priority. Refer to Section 10.1.4, Procedures to Turn On the 
Class Scheduler, for details. Dedicating a system in this manner is 
especially useful when there are many long-running batch jobs at an 
installation. 

Another suggestion is to put software development jobs on one system 
and production jobs on another. Also, you may want to keep one system 
lightly loaded for critical jobs. 

DBMS applications, and programming applications requiring 
ENQUEUE/DEQUEUE or IPCF facilities must be confined to one system. 
These are other items to consider if you choose to establish certain 
uses for particular systems. 

Keep in mind that users must log onto the systems that are to run 
their particular jobs. This applies to batch jobs also (without 
DECnet) . Batch jobs must be submitted by a user logged in on the 
system where they are to run. The control and log files may reside on 
shared disks. 



12.3.2 Assigning Users to Systems 

In the CFS environment, much of the load balancing is expected to be 
performed by users. The systems, for example, do not detect that one 
CPU is overburdened and that another one is underutilized, and, 
accordingly, reassign users' jobs. Instead, users themselves could 
determine whether or not they should log off a system and log onto 
another one when system response is slow. Such user tools as the 
SYSTAT and INFORMATION SYSTEM commands and the CTRL/T function can 
help users in this area. These tools report on the current state of a 
system. Among the items reported are the number of jobs running on a 
system, load averages, the current setting of the bias control "knob," 
and whether batch jobs are assigned to a special class. However, they 
report only on the user's logged-in system, not on others in the 
configuration. 

If you choose this load balancing scheme, you should create 
directories for all users on all the public structures in the CFS 
configuration. Also, directory usernames should be unique throughout 
the configuration, as described below. Then, users can log onto any 
system with no problem. 
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USERNAMES 

Directory usernames should be unique throughout the CFS configuration. 
For example, there should be only one user with the username <BROWN> 
at an installation. This lets users access system resources without 
encountering password-related obstacles or causing security breaches. 

If two users on different systems have the same usernames but 
different passwords, their passwords will be invalid when they switch 
systems. If these same users should by chance have the same 
passwords, they will have complete access to each other's files when 
they switch systems. Also, if a structure is mounted on both systems 
as domestic, neither user will have to give a password when accessing 
the directory on that structure that has their username. (Refer to 
Section 4,5.7, Mounting Structures from Another Installation, for a 
discussion of foreign and domestic structures.) 

DIRECTORY AND USER GROUPS 

To facilitate user access to CFS files, you could make directory and 
user group numbers consistent on all structures. That way, users 
could change structures or systems and their access attempts would 
have predictable outcomes. 



12.4 STRUCTURE NAMES 

Because the structures on all systems are part of a unified file 

system, structure names must be unique throughout the CFS 

configuration. For example, two systems cannot each have a public 
structure mounted with the name PS:. 

If it is necessary to mount structures with duplicate names, the 
operator should mount one of the structures using an alias. (Refer to 
Section 4.5.2, Mounting Structures Having the Same Name.) The system 
recognizes a structure by its alias, which is the same as the 
permanent structure identification name, unless otherwise specified. 
Note that everyone throughout the CFS configuration must refer to a 
structure by the same alias. 



12.5 SYSTEM LOGICAL NAMES 

Logical names are implemented differently from structure names and 
their aliases. Logical names are local definitions that need not be 
unique nor consistent throughout the CFS configuration. Thus, the 
same logical name on two different systems can refer to two completely 
different disk areas. However, because users are likely to be mobile, 
system-wide logical names should be consistent across systems. This 
will avoid confusion for users who switch systems. 

Refer to Section 3.3, SYSTEM-LOGICAL NAMES, for further information. 
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12.6 SHARING STRUCTURES AMONG SYSTEMS 

By default, all structures in the CFS configuration are accessible to 
all systems, provided outside paths have been established for massbus 
disks where necessary, using the ALLOW command (refer to Section 
12.1.1, CFS HARDWARE). It is necessary to "mount" a structure on any 
system that is to access files on it, however. That is, the operator 
or a user on that system must issue a MOUNT command for the structure. 
(There can be up to 32 structures online on one system.) After a 
structure is mounted on a system, users can access it as on non-CFS 
systems. Users have automatic access to their public structure files, 
as on non-CFS systems. 

If a structure has been restricted to a system through previous use of 
the operator command, SET STRUCTURE str: EXCLUSIVE, it can be made 
sharable again with the SET STRUCTURE str: SHARED command. The 
operator issues this command from a terminal running OPR on the system 
that has exclusive use of the structure. Then, MOUNT commands can be 
issued for the structure that has been made sharable. The default 
setting for structures is sharable. 

The operator command, SHOW STATUS STRUCTURE, indicates the shared or 
exclusive status for all structures known to a system. 

STRUCTURE ATTRIBUTES 

The operator specifies attributes for a structure with the SET 
STRUCTURE command, as described in the TOPS-20 Operator's Command 
Language Reference Manual . They are permanent settings that do not 
revert to default values after system crashes and reloads. 

Note that all systems need not have the same attributes in effect for 
a structure. For example, one system can have a structure mounted as 
foreign and regulated, and another system can have the same structure 
mounted as domestic and unregulated. Except for SHARED and EXCLUSIVE, 
attributes are on a single-system basis only. 



12.6.1 Sharing Public Structures 

Bear in mind that when public structures are shared, privileged users 
can create privileged accounts on any public structure, with the 
"ECREATE command. This may or may not be desirable. 



12.7 RESTRICTING STRUCTURES TO ONE SYSTEM 

There may be times when you want to restrict use of a structure to a 
particular system. Such a structure might be used for DBMS 
applications (refer to Section 12.1.6, Limitations) , or security 
measures may call for restricted use. For whatever reason, the 
operator restricts a structure with the following command: 

OPR> SET STRUCTURE Str: EXCLUSIVE 
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When the operator gives this command, the system first checks to see 
that the structure is not in use on another system. If it is, the 
operator must dismount the structure from the other system (with the 
NO-REMOVAL option) , using a terminal running OPR on that system. The 
operator follows the normal dismount procedure of making the structure 
unavailable to new users and notifying existing users of the pending 
dismount. The structure should be kept unavailable for all systems 
except the exclusive one so that the structure will not be 
inadvertently shared when the owning system crashes. 

After a structure has been dismounted from other systems, the SET 
STRUCTURE EXCLUSIVE command can take effect. It remains in effect on 
the system, as do all SET STRUCTURE specifications, throughout crashes 
and reloads. If users give the MOUNT command for a structure that is 
exclusive to another system, an error message will be issued, 
indicating that the structure is unavailable. 

Note that any system can have exclusive use of any sharable structure 
except another system's public structure. 



12.8 DISMOUNTING STRUCTURES 

When issuing a DISMOUNT command for a structure, operators have the 
option of specifying that the structure be physically removed from a 
disk drive. In the CFS environment, however, the system first ensures 
that the structure is not in use on other systems. If a structure is 
mounted on another system, the operator is notified and must go 
through the normal procedure of dismounting the structure (with the 
NO-REMOVAL option) from that system. Refer to the TOPS-20 Operator' s 
Guide for details. 

The default setting on CFS systems is for a structure to be dismounted 
with the no-removal option. 

Sometimes the system may instruct the operator to dismount structures. 
This occurs when the operator attempts to either shut down a system or 
make the CI unavailable to a system. Refer to Sections 12.9 and 12.12 
for details. 



12.9 MAKING THE CI UNAVAILABLE TO A SYSTEM 

Ordinarily, you need do nothing at all to operate the CI. However, 
you may need to disengage a system from the CI so Field Service 
personnel can diagnose and/or correct problems with the CI20 or the 
HSC50. Or, you may wish to remove a system from the CFS 
configuration. At those times, you should instruct the operator to 
make the CI unavailable by means of the SET PORT CI UNAVAILABLE 
command. (Refer to the TOPS-20 Operator's Guide for details.) 

When the CI is unavailable to a system, users cannot access 
multi-access disks (dual-ported disks, HSC50-based disks, or served 

disks on other systems) . These disks rely on the CI to coordinate 

accesses and/or to transmit data. Served disks on the system 

disengaging from the CI will be unavailable to other systems. 

Dual-ported massbus disks in the A/B position will have to be powered 
down and switched to one system. 
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When the operator gives the SET PORT CI UNAVAILABLE command, the 
system indicates the structures that need to be dismounted and the 
disk drives that need to be made unavailable. The operator is advised 
to follow the normal procedures of forewarning users before 
dismounting structures and making disk drives unavailable. The 
command option to forcibly disengage a system from the CI should be 
reserved for emergencies. If the operator determines that disengaging 
from the CI will be too disruptive to users, the operator has the 
option of aborting the procedure. 

To put the CI back in operation, the operator gives the command: 

OPR>SET PORT CI AVAILABLE 

The operator is then asked if any other TOPS-20 system is running on 
the CI. If yes, the system rejoining the CFS configuration must be 
rebooted. If no, the CI20 will be reloaded and started. A CFRECN 
BUGHLT is issued on the processor with the lower serial number if the 
operator answers "no" and another TOPS-20 system is found after the 
CI20 has started. (See Section 12.11.1 for details.) After the system 
rejoins the configuration, structures that were affected when the CI 
was made unavailable will need to be remounted. 



12.10 USING DUMPER 

CFS offers operators and users flexibility in saving and restoring 
disk files. The only restriction is that DUMPER must be running on a 
system to which tape drives are attached. Tape drives are not served 
through CFS. 



12.11 ERRORS 

This section discusses the actions you or the operator take when 
errors occur in the CFS environment. It also describes how CFS 
systems react to various errors. Note that there is no single 
hardware or software point that can disable the whole configuration. 
For example, systems can start up or crash with little impact on other 
systems. 



12.11.1 Communication Problems 

CFS systems are sensitive to breaks in communication, whether they are 
caused by CI20 errors or system crashes. Because the data integrity 
of shared structures depends on unbroken intersystem contact, the 
systems take quick action to prevent data corruption. Therefore, you 
may observe any of the following when systems lose contact with each 
other. These should be rare occurrences. 

• For up to 15 seconds, no system in the configuration can 
access any multiaccess disks (dual-ported disks, HSC50-based 
disks, served disks on other systems). 



12-14 



THE COMMON FILE SYSTEM 



The 15 seconds allows each system to check that its own CI20 
and segment of the CI bus are working. Most likely, some 
system's CI20 microcode has stopped and is automatically 
reloaded during the interval, or a system has crashed. 
(There may be other, unpredictable reasons for CI 
disruption.) Jobs that were accessing multiaccess disks are 
suspended until data integrity is assured. 

If the CI20 and CI bus are working before the end of the 
interval, the system can resume accessing all multiaccess 
disks except server disks on a crashed system. 

• A system crashes with a KLPNRL BUGHLT. This happens if the 
CI20 microcode takes longer to reload than 10 seconds. This 
BUGHLT is expected to occur rarely, because the microcode 
should be reloaded within a couple of seconds. 

• In a two-system configuration, if communication resumes after 
the 15-second allowance, without one of the systems having 
crashed and restarted, the system with the lower serial 
number crashes with a CFRECN BUGHLT message. For example, 
this occurs when the SET PORT CI AVAILABLE command has caused 
communication to resume incorrectly due to operator error, as 
described in Section 12.9, MAKING THE CI UNAVAILABLE TO A 
SYSTEM. 

With such a delayed reconnection, a system is likely to 
contain old, invalid information about the status of 
multi-access disks. This is because the other system is 
allowed to access the disks after the 15 seconds, believing 
the other system is no longer running. Therefore, the system 
with the lower "serial number is selected to crash so that a 
fresh data base can be established for the disks when the 
system restarts. 



12.11.2 Massbus Problems with Dual-Ported Disk Drives 

Dual-ported disk drives are accessed by each system through the 
massbus hardware connections. However, if for some reason a massbus 
path becomes unavailable to a system, the other system, with working 
massbus connections, can provide access to the drives affected, with 
the MSCP file server. The disks become "served." 

The operator enables this facility by powering down the disks and 
flipping the drive port switches from the A/B position to the position 
that corresponds to the servicing system. Then the operator must 
reboot the system with the faulty massbus link. These procedures are 
required because a running system will never invoke the MSCP server 
after identifying a massbus path for a disk. It is assumed that an 
ALLOW command has been entered in the n-CONFIG.CMD file for the disk 
drives, as described in Section 12.1.1, CFS Hardware. 

The operator returns the switches to the A/B position when the massbus 
problem is corrected. The PHYTPD BUGINF is then issued to confirm 
that the massbus will now be used for data transmission. 



12-15 



THE COMMON FILE SYSTEM 

12.12 SHUTTING DOWN A CFS SYSTEM 

When an operator issues the "ECEASE command to shut down a system, 
outside jobs that may be accessing the system's served disks do not 
hang, with the following procedure. If any served disks have been 
mounted from other CFS systems, the operator is warned to check those 
systems for possible structure dismounting instructions. 

At the other systems, meantime, if any served disks are mounted on the 
system shutting down, the operator is warned of the pending shutdown 
and is advised to dismount the structures listed. 
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CHAPTER 13 
LAT TERMINAL SERVERS 



13.1 OVERVIEW 
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area network is a collection of computers and their resources 
linked together in a small geographic area, such as a college 

r a large building. Local Area Transport ( LAT ) software 
special-purpose computers to be used as terminal servers in 
network. With LAT software, user terminals that would 

e be individually wired to host systems (DECSYSTEM-20S, for 
are instead connected directly to a LAT terminal server. The 

in turn, is linked to one or more hosts by way of the Ethernet 

Interconnect cable (NI), as shown below: 
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Figure 13-1: A LAT Network 



A LAT host might be a TOPS-20, VMS, or RSX-11 system. The LAT server 
is any Nl-based terminal server. 

The main features of LAT servers are: 

• Users can connect to any NI host that supports the LAT 
protocol, and it appears to them that their terminals have 
direct connections to those hosts. Connections between LAT 
terminal users and hosts are called sessions . There can be 
up to 128 sessions on a TOPS-20 host. 

• By requesting multiple host connections, a LAT terminal user 
can enable multiple sessions at one host or at several hosts 
simultaneously. With one keystroke, such users can switch 
between their jobs on these systems. 
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• LAT servers can balance user loads among hosts according to a 
rating system that you set up. 

Note that LAT software runs on host systems as well as on LAT servers. 
This chapter discusses how to control LAT host software from a 
DECSYSTEM-20. You can also issue commands directly to a LAT terminal 
server. Refer to the documentation provided with your LAT terminal 
server hardware for details on those commands. 



13.2 LAT SOFTWARE 

Each host that supports the LAT protocol for interactive terminal 
service periodically broadcasts this fact to all LAT terminal servers. 
Each server maintains a list of hosts that have sent such messages. A 
terminal user can issue a command to the server to display this list 
to see which hosts are accessible. 

The logical path between a LAT host and server is called a LAT virtual 
circuit . There is one virtual circuit for each server/host pair that 
has at least one active terminal session. When a terminal user 
requests a connection to a host, the server creates a virtual circuit 
to that host if none exists. Otherwise an already existing circuit is 
used for data transmission. As system manager, you can decide the 
maximum number of virtual circuits that can exist at a host. The 
number that you decide upon can affect system performance. This topic 
is discussed in Section 13.4. 

Virtual circuit messages are transmitted between host and server at 
periodic intervals determined by a circuit timer maintained in the LAT 
server. When the timer expires, the server assembles into a single 
virtual circuit message any terminal input received during the past 
interval for a particular host and transmits it to the host. You can 
set this timer only at the server. It has a recommended value of 80 
milliseconds, which is the default. 

The data associated with a particular terminal are grouped in a 
virtual circuit message in units called slots . A virtual circuit 
message may contain slots from many terminals and may contain more 
than one slot from a single terminal. The maximum size of a slot is 
another parameter that you can set. 

Having received a virtual circuit message, the host assembles as much 
terminal output data as possible into a single message and transmits 
it to the server. If no output is waiting for any terminal at that 
server, a message is sent with no slots. The host's response message 
acknowledges the previously received message from the server. This 
message will be acknowledged by the server message transmitted at the 
next tick of the circuit timer. 

To reduce NI utilization and load on the host, the server transmits a 
message only when there is something to send. It could happen that 
when the server has no data to transmit, there is more terminal output 
data waiting at the host. But because the last host message remains 
unacknowledged, output flow from the host would stop. For this 
reason, the host is permitted to transmit one "unsolicited" message to 
the server. (Refer to the description of the HOST RETRANSMIT TIMER 
dynamic parameter in Section 13.4 for additional information.) The 
host sets a flag in the message, which forces the server to respond at 
the next tick of the circuit timer. This "forced" response 
acknowledges all the host's previously transmitted messages and 
returns all transmit buffers so that they may be used again. 
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The host maintains a circuit timer with a default interval of 1 
second. (You can set it up to 2 seconds.) The function of the host's 
circuit timer differs from that of the server's circuit timer: it is 
used solely as a retransmit timer . When the host sends an 
"unsolicited" message, as described above, it starts its circuit 
timer. Because the server's circuit timer is shorter than the host's, 
the server should have acknowledged all outstanding host messages well 
before the host's timer expires. If this does not happen, the host 
retransmits all unacknowledged messages. This continues until either 
the server responds with an acknowledgement, or the retransmit limit 
is reached. If the retransmit limit is reached, the host assumes the 
connection to the server is no longer useable and detaches all LAT 
jobs from that server. (Refer to the description of the HOST 
RETRANSMIT TIMER and the HOST RETRANSMIT LIMIT dynamic parameters in 
Section 13.4.) 



13.3 DECNET 

LAT, for the most part, is independent of DECnet. It does not require 
DECnet for general operations. However, DECnet is required on at 
least one host for start-up of LAT servers. Software from a host is 
loaded into the server's memory by DECnet' s Network Management. This 
"down-line loading" of LAT servers occurs when the operator either 
physically boots the server or triggers a boot of the server by 
issuing a DECnet command from a host running DECnet. In either case, 
any host that has DECnet and the appropriate load files may respond to 
the boot, and then be selected by the server to load its memory. 
DECnet is also needed for "dumping" files of LAT memory images to a 
host for problem diagnosis on the host. Refer to the DECnet-20/PSI-20 
System Manager' s Guide for" the operator procedures involved in loading 
and dumping LAT servers. 

If a system supports DECnet, its node name and number are taken to be 

the LAT name and number also. You do not need to respecify them in 

the n-CONFIG.CMD file. Refer to the discussion of static parameters 
in Section 13.4. 



13.4 CONTROLLING LAT FROM THE HOST 

There are three ways for you or the operator or a system programmer to 
control LAT from a host: 

• By rebuilding the monitor with new permanent parameters. 

• By changing static parameters in the n-CONFIG.CMD file 

• By changing dynamic parameters with the LAT Control Program 
subsystem of the OPR program 

The lists below briefly describe these parameters. Many are discussed 
more fully later. 

Note that you can also control LAT from the server itself. Refer to 
the documentation that came with your LAT server for details on server 
commands. 
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Permanent Parameters 

Normally, you do not need to change permanent parameters. To change 
them, a system programmer familiar with monitor internals must rebuild 
the monitor. 

• FRAME SIZE - The host or server guarantees that it can 
receive NI datagrams of at least this size. Usually three ( 
2 transmit and 1 receive) buffers of this size; are used for 
each LAT circuit. The default and recommended value is 1504 
bytes. 

• MAXIMUM HOST SERVICES - Sets the maximum number of services 
that this host can offer. You can specify up to 254 
services. The default and recommended maximum is 8. Refer 
to Section 13.7, HOST SERVICES. 

• MAXIMUM SLOTS - Sets the maximum number of slots that may be 
entered into a virtual circuit datagram for a given circuit. 
It is agreed upon by the server and host when the virtual 
circuit between them is established. The default and 
recommended value is 64. 

• MAXIMUM SLOT SIZE - Sets the maximum number of bytes of data 
(not including the slot header) that the host can accept from 
the server in any slot. The slot size can range from 1 to 
255. The default and recommended value is 40. 

• MAXIMUM SERVER CACHE - Sets the maximum number of servers 
whose characteristics are kept in memory. The LCP command, 
SHOW SERVER, displays these characteristics. (Refer to 
Section 13.8.3, Displaying Server Information.) The default 
and recommended value is 20. 

Static Parameters 

• DEFAULT LAT ACCESS STATE - Determines LAT accessibility to 
and from the host. Values for the state are ON (the default) 
and OFF. The LAT access state can be changed dynamically 
with a LAT Control Program command. Whein the system is 
reloaded, however, the value for this static parameter again 
takes effect. 

Refer to Section 13.5, STARTING AND STOPPING LAT, for 
additional information. 

• HOST NAME - Uniquely identifies the host within the local 
area network. It may contain up to a combination of six 
alphabetic and numeric characters, with at least one 
alphabetic character. The default host name is the DECnet 
node name, if the system supports DECnet. If the system does 
not support DECnet, you must specify a name. For related 
information, refer also to Section 13.7. That section 
discusses host service names . 

• HOST NUMBER - Uniquely identifies the host within the local 
area network. The number can range from to 65535. It is 
passed to the server when the virtual circuit between host 
and server is established. The default number is the DECnet 
node number, if the system supports DECnet. This is an 
optional parameter for use by one of your system programmers. 



13-4 



LAT TERMINAL SERVERS 

The n-CONFIG.CMD file commands that set these static parameters are: 
NODE hostname hostnumber 
LAT-STATE default LAT access state 
where the default LAT access state is ON or OFF 

Dynamic Parameters 

As system manager, you will probably be most concerned with dynamic 
parameters: 

• HOST GROUP CODES - Defines the group codes for the host. 
They can range from to 255. Code is enabled by default. 
You can define any number of codes for a host. A LAT server 
will not connect to the host unless both server and host have 
at least one group code defined in common. Refer to Section 
13.7, LAT GROUPS. 

• HOST IDENTIFICATION - Supplies information about the host. 
It appears in various displays requested by managers and 
users. The identification may contain up to 64 printable 
characters. The default identification is the TOPS-20 banner 
message from SYSTEM: MONNAM.TXT. 

• HOST NUMBER - Uniquely identifies the host within the local 
area network. The number can range from to 65535. It is 
passed to the server when the virtual circuit between host 
and server is established. The default number is the DECnet 
node number if the system supports DECnet. This is an 
optional parameter for use by one of your system programmers. 

• HOST MULTICAST TIMER - Determines the interval at which the 
host announces to all servers that its LAT terminal service 
is available. The default value is 60 seconds. 

• HOST RETRANSMIT LIMIT - Sets the maximum number of times that 
the host retransmits a message at the expiration of HOST 
CIRCUIT TIMER. The virtual circuit is closed and all jobs 
associated with the virtual circuit become detached when this 
limit is exceeded. The default value is 30 times. 

• HOST RETRANSMIT TIMER - Determines the interval at which the 
host retransmits any unacknowledged messages to the server. 
It is started when the host sends an "unsolicited" message 
and is stopped when the host receives any message from the 
server that acknowledges all outstanding messages. The 
default value is 1000 milliseconds (one second) . It can be 
set from 1000 to 2000 milliseconds, however. Refer to the 
description of the HOST RETRANSMIT LIMIT parameter for 
related information. 

• HOST SERVICE NAME - Specifies the name of a service that the 
host provides for users. It may contain a combination of up 
to 16 alphabetic and numeric characters as well as the dollar 
sign ($) „ dash (-) , and underscore (_) . The default service 
name is the host name. Refer to Section 13.7, HOST SERVICES. 
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• HOST SERVICE NAME RATING - Assigns a rating to a service 
name. It can be a fixed number in the range of to 255 or 
it can be DYNAMIC. Refer to Section 13.7.1, Service Ratings. 

• LAT ACCESS STATE - Determines LAT accessibility to and from 
the host. The default state allows LAT access. This dynamic 
parameter is affected by the LCP START and STOP commands. 

• MAXIMUM ACTIVE CIRCUITS - Sets the maximum number of LAT 
virtual circuits that can exist simultaneously at the host. 
The default value is 20. 

• MAXIMUM SESSIONS - Sets the maximum number of terminal 
sessions that may be active at the host simultaneously. The 
default value is equivalent to the number of terminals 
allowed in your system configuration. Section 13.1 discusses 
sessions. 

The dynamic parameters are changed with the LAT Control Program (LCP). 
To use LCP, the operator enters the following from the OPR prompt: 

1. For many LCP commands: 

OPR> ENTER LCP 
LCP> <LCP command> 
LCP> <LCP command> 
LCP> <LCP command> 
LCP> <LCP command> 
LCP> RETURN 
OPR> 

2. For a single command: 

OPR> LCP <LCP command> 
OPR> 

The LCP commands also let you start and stop operations, check 
parameter values and other information, and access counters maintained 
by the NI and servers. These LCP functions are discussed in later 
sections. The Operator' s Command Language Reference Manual fully 
describes LCP. 
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The following is a summary of the LCP commands: 

START 
STOP 

SET GROUPS (0,1-5, ....255) 

SET SERVICE-NAME service-name{/RATING: {nn |DYNAMIC} 

/IDENTIFICATION: "text" I 
nothing} 
SET IDENTIFICATION "text" 
SET NUMBER number 

SET MAXIMUM ACTIVE-CIRCUITS number 
SET MAXIMUM SESSIONS number 
SET MULTICAST-TIMER seconds 
SET RETRANSMIT LIMIT number 
SET RETRANSMIT TIMER number 

CLEAR GROUPS (0 , 1-5, . . . . 255) 

CLEAR SERVICE-NAME service-name 

CLEAR IDENTIFICATION 

CLEAR MAXIMUM CIRCUITS 

CLEAR MAXIMUM SESSIONS 

CLEAR MULTICAST-TIMER 

CLEAR NUMBER 

CLEAR RETRANSMIT LIMIT 

CLEAR RETRANSMIT TIMER 

SHOW CHARACTERISTICS 

SHOW SESSIONS 

SHOW COUNTERS {/SERVER: server-name | 

nothing} 
SHOW SERVER {/ALL | 

server-name I 

nothing} 

ZERO COUNTERS {/SERVER: server-name | 
no th i ng } 



13.5 STARTING AND STOPPING LAT 

Support for LAT servers is enabled by default in TOPS-20. That is, 
the LAT access state is enabled unless specifically disabled in the 
n-CONFIG.CMD file. Disabling it is useful if you wish to establish 
guidelines and set restrictions for LAT use before you enable it. You 
can set groups and the host identification, for example, before 
enabling LAT. The operator can enable and disable the LAT access 
state dynamically with the LCP START and STOP commands. 

The host name and number are other parameters that you specify in the 
n-CONFIG.CMD file (unless DECnet is supported on the host). They are 
required items that uniquely identify the host in the local area 
network. 

After the host name and number have been established, and the LAT 

access state has been enabled, the operator starts LAT by booting the 

server or by issuing a DECnet command from the host, as discussed in 
Section 13.3. 

It is recommended that you disable the LAT access state if LAT is not 
intended to be used for an extended period of time. This will improve 
system performance. 
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13.6 LAT GROUPS 

By using group codes , you can divide the local area network into 
smaller networks. That is, you can allow or prevent connections 
between specified servers and hosts. When users give a LAT command to 
display the names of available services, only those services 
corresponding to hosts within a server's "group" are displayed. 
{Refer to Section 13.7 for a discussion of services.) Codes in the 
range of to 255 can be assigned to DECSYSTEM-20S and LAT servers. A 
LAT server will connect to a host only if it has at least one group 
code defined in common with the host. (Refer to the LAT documentation 
set for information on assigning codes to LAT servers.) Note that code 
0, the default for hosts and servers, allows universal access. When 
servers and hosts implement the default, users have access to all 
hosts. 

In the example below, an operator enables access between this 
DECSYSTEM-20 and any LAT server assigned a code in the range of 1 to 
5. No connection is allowed with any other server. 

LCP> SET GROUPS 1:5 
LCP> CLEAR GROUPS 

User terminals wired to servers in any one of these groups will be 
able to access the system. 

Group settings stay in effect until reset with the CLEAR GROUPS 
command. 



13.7 HOST SERVICES 

Another name for a LAT host is a service node (a node being a system 

in a network) . This refers to the fact that hosts provide computing 

services . Users access hosts in order to have some type of computing 

need served — to compile a program, update a file, or print a report, 

for example. LAT terminal servers deliver these services to users. 

Users refer to hosts by the services that they offer, rather than by 
host name. When they request the LAT server to connect them to a 
host, they specify a service name that you have previously established 
for that host. The server maintains a list of host and service names 
and lets users display service names assigned to hosts in the user's 
group. (The server also displays any service identification text you 
specified.) With the SET SERVICE-NAME command, you can specify one or 
more services for a host: 

LCP> SET SERVICE-NAME LASER-PRINTER/IDENTIFICATION: "OMEGA System" 
LCP> SET SERVICE-NAME ARPA-GATEWAY 

The default service name for a host is the host name. You may want to 
specify some identifying text for such services. For example, on the 
host ALPHA, you could give the command: 

LCP> SET SERVICE-NAME ALPHA/IDENTIFICATION: "A DECnlet System" 

You can assign the same service name to multiple hosts. The following 
section discusses this topic. 
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13.7.1 Service Ratings 

You can arrange for LAT servers to distribute users among host 
systems, according to a rating system that you set up. This is useful 
for hosts with service names in common. Perhaps several systems are 
part of a CFS cluster. You can assign the same service name, CFS, on 
each host but specify a unique service rating for each one: 

LCP> SET SERVICE-NAME CFS/RATING: 3/I0ENTIFICATI0N !" ALPHA/BETA/OMEGA Cluster - 
LCP> SET SERVICE-NAME CFS/RATING ^/IDENTIFICATION: - ALPHA/BETA/OMEGA Cluster" 

If a user requests connection to CFS, the server will pick the host 
with the highest rating for that service. If, for some reason, that 
connection fails, the server will try the host with the next highest 
rating. 

Ratings can be a fixed number from to 255. Or they can be DYNAMIC. 
When hosts with common service names have DYNAMIC ratings for the 
service, the hosts compute ratings using an algorithm based on system 
load averages. Generally, the host with the lowest load average is 
given the highest rating. That host probably has the greatest 
available computing capacity. 

You can use common service names for any collection of hosts offering 
the same function. 

The default rating is 1 for the default service name, and for 
services created with the SET SERVICE-NAME command. 

Service Rating Example 

Hosts SOLAR and LUNAR, in addition to providing a timesharing service 
as service names SOLAR and LUNAR, each have the service name CFS. 
SOLAR assigns a host rating to name CFS of 5; whereas LUNAR assigns 3. 
A LAT terminal user, when displaying the list of available LAT 
services, will see SOLAR, LUNAR, and CFS. If the user connects to 
CFS, the server will first attempt to access SOLAR. If that fails, it 
will try LUNAR. 



13.8 MONITORING LAT FROM THE HOST 

The following sections show various LAT informational displays, 
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13.8.1 Displaying User Information 

The SHOW SESSIONS command displays information about connected LAT 
terminals: 

LCP>SHOW SESSIONS 

LCP> 

17:06:46 [LCP] Connected LAT Terminals 



Job 


Line 


Program 


Server Name 


User 


221 


460 


EXEC 


Accounting 


MCCOLLUM 


208 


461 


EXEC 


Accounting 


GLINDELL 


209 


462 


EXEC 


Accounting 


BRAITHWAITE 


213 


463 


EXEC 


Finance 


DDANTONIO 


207 


465 


MS 


Accounting 


MAYBERRY 


211 


467 


EGPEGP 


Accounting 


PAETZOLD 


205 


470 


EXEC 


Accounting 


LOMARTIRE 


217 


471 


OPR 


Finance 


TUCKER 


219 


472 


EXEC 


Payroll 


MELOHN 



The TOPS-20 SYSTAT user command shows this same information. 



13.8.2 Displaying Host Parameters 

The SHOW CHARACTERISTICS command displays many of the LAT parameter 
settings: 

LCP>SHOW CHARACTERISTICS 

17:15:13 [LCP] Host Characteristics 

LAT Access State: ON 

Host Name: ALPHA 

Host id: ALPHA (KL3138)), TOPS-20 Development System, TOPS-20 Monitor 6.1 

Host number: 142 

Maximum allocated circuits: 20 

Currently allocated circuits: 4 

Maximum active circuits: 20 

Currently active circuits: 4 

Maximum sessions: 32 

Current sessions: 2 

Retransmit Limit: 60 

Retransmit Timer: 50 

Multicast Timer: 30 

Groups: 2,4 

Service name( rating) : ALPHA(l) 

Service Id: Alpha - More Networks per CPU 

Service name( rating) : ALBET(D) 

Service Id: Alpha/Beta Cluster 

The "(D)" that appears for the service name rating indicates a dynamic 
rating. 
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13.8.3 Displaying Server Information 

The SHOW SERVER command displays information about servers with 
connections to this host. The host tries to keep information in 
memory on all servers that have connected since the last monitor load. 
However, this could require a very large data base. Therefore, 
information is kept only for the number of servers specified in the 
MAXIMUM SERVER CACHE permanent parameter. (Refer to Section 13.4 for 
information on this parameter.) When this number is exceeded, the 
oldest inactive entry is deleted from the data base, making room for a 
new entry. 

You can specify a single-line summary for each server or a detailed 
display for a single server: 

LCP>SHOW SERVER/ALL 

LCP> 

14:55:32 [LCP] Summary of all servers 

Server Name(Number) : Finance(8) Address: 08-00-2B-00-17-BA 

Server Name (Number) : Accounting (22) Address: 08-00-2B-02-08-C0 

Server Name(Number) : Payroll [LAT3] (3) Address: AA-00-03-01-25-38 

Server Name (Number) : Development (2) Address: AA-00-03-01-06-AB 

LCP>SHOW SERVER FINANCE 

LCP> 

14:56:12 [LCP] Information about server Finance 

Server Number: 8 

Server Location: Near vending machines 

Server Type: DECserver-100 

Ethernet Address: 08-00-2B-00-17-BA 

Server Status: Connected 

Max Slots: 32 

Data Link Size: 1518 

Circuit Timer(ms): 80 

Keep-alive Timer(s): 20 
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13.8.4 Displaying LAT Counters 

The SHOW COUNTERS command displays counters kept by LAT software 
modules. These counters provide information such as the number of 
messages transmitted, the number of transmission errors, and so on. 
You can obtain these numbers for a single server, or you can obtain 
cumulative figures for all servers that have connected since the last 
monitor reload: 

LCP>SHOW COUNTERS 

LCP> 

14:48:11 [LCP] Counter totals for all servers 

Messages received: 33955 
Messages transmitted: 36413 
Messages retransmitted: 
Sequence errors received: 21 
Illegal messages received: 
Illegal slots received: 
Resource failures: 



LCP>SHOW COUNTERS/SERVER: PUBLICATIONS 

LCP> 

14:48:34 [LCP] Counters for server PUBLICATIONS 

Messages received: 28189 
Messages transmitted: 30132 
Messages retransmitted: 
Sequence errors received: 
Illegal messages received: 
Illegal slots received: 
Resource failures: 

The single-server counts are available even after a server has 

disconnected from the host. However, this availability, as the 

information displayed with the SHOW SERVER command, depends on the 
limit set with the MAXIMUM SERVER CACHE permanent parameter. 

The cumulative counters are incremented each time individual server 
counters are. It is possible that the sum of all server counters is 
not equal to the cumulative counts, because you can zero the counters 
for any server, as discussed below, or the data base may have been 
cleared according to the MAXIMUM SERVER CACHE parameter limitation. 

When using the counters to monitor performance or to isolate hardware 
failures, it is often desirable to be able to reset (or zero) the 
counters. The ZERO COUNTERS command lets you do this. You can reset 
counters for one server or for all the servers. Resetting the 
cumulative counts does not affect the counts of the individual 
servers. 
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APPENDIX A 
THE BUILD COMMAND 

NOTE 

The information previously found in Appendix A has 
been removed. The BUILD command is described in the 
TOPS-20 Commands Reference Manual . Refer to the 
TOPS-20 Operator's Command " Language Reference Manual 
for a description of the "ECREATE command. 
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